mirror of
https://github.com/dexoron/dcr.git
synced 2026-10-21 08:58:35 +00:00
285 lines
12 KiB
Plaintext
285 lines
12 KiB
Plaintext
---
|
||
sidebar_label: dcr.toml overview
|
||
---
|
||
|
||
# dcr.toml
|
||
|
||
Main project configuration file. Located at the project root.
|
||
|
||
## Structure
|
||
|
||
```toml
|
||
[package]
|
||
# required fields
|
||
|
||
[build]
|
||
# build settings
|
||
|
||
[build.debug] # optional: debug override
|
||
[build.release] # optional: release override
|
||
|
||
[build.linux] # optional: Linux override
|
||
[build.windows] # optional: Windows override
|
||
[build.windows.debug] # target + profile combination
|
||
|
||
[toolchain]
|
||
# compiler/linker paths
|
||
|
||
[dependencies]
|
||
# project dependencies
|
||
|
||
[workspace]
|
||
# multi-package configuration
|
||
|
||
[run]
|
||
# run settings
|
||
|
||
[archive]
|
||
# optional: pack FAT disk image after build
|
||
```
|
||
|
||
## [package]
|
||
|
||
| Field | Required | Description |
|
||
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
|
||
| `name` | yes | Project name |
|
||
| `version` | yes | Semantic version of the **project** |
|
||
| `dcr-version` | no | Semver of the **dcr tool** this project targets. Written by `dcr new` / `dcr init` to the current tool version. |
|
||
| `type` | no | `app`, `lib`, `none` (defaults to `"none"`) |
|
||
| `license` | no | SPDX license identifier |
|
||
| `author` | no | Author |
|
||
|
||
```toml
|
||
[package]
|
||
name = "my-app"
|
||
version = "0.1.0"
|
||
dcr-version = "0.8.4"
|
||
type = "app"
|
||
license = "MIT"
|
||
author = "John Doe"
|
||
```
|
||
|
||
### `package.dcr-version`
|
||
|
||
Optional pin of the DCR CLI the project was written for. On every `dcr.toml` load:
|
||
|
||
| Situation | Behaviour |
|
||
| ------------------------------ | ---------------------------------------------------------- |
|
||
| Field missing / empty | Warning: add `dcr-version` (set by `dcr new` / `dcr init`) |
|
||
| Running dcr **older** than pin | Warning: upgrade dcr (`dcr --update`) |
|
||
| Running dcr **newer** than pin | Warning: review changelog, bump the pin when ready |
|
||
| Equal | Silent |
|
||
| Invalid semver | Warning once, field ignored |
|
||
|
||
Never fails the command — warnings only. Pre-release suffixes (`1.0.0-dev`) are ignored for comparison (`1.0.0-dev` ≡ `1.0.0`).
|
||
|
||
## [build]
|
||
|
||
...
|
||
|
||
* `build.qt` — (bool) Enable automatic Qt meta-object handling (MOC, UIC, RCC). Requires `qt6` modules installed via `pkg-config`.
|
||
|
||
| Field | Default | Description |
|
||
| ---------------- | ------------- | --------------------------------------------------------------------------------------------------------- |
|
||
| `language` | `"c"` | `"c"`, `"c++"`, `"cpp"`, `"cxx"`, `"asm"`, `"llvm_ir"`, `"llvm-ir"`, `"ll"` (optional, defaults to `"c"`) |
|
||
| `standard` | `"c11"` | C standard (`c11`, `c17`, `c23`) |
|
||
| `cxx_standard` | — | C++ standard (`c++17`, `c++20`, `c++23`) |
|
||
| `compiler` | `"clang"` | Preferred compiler (optional, defaults to `"clang"`) |
|
||
| `kind` | `"bin"` | `bin`, `staticlib`, `sharedlib`, `efi`, `elf`, `none`, `custom`, `flat-bin` |
|
||
| `target` | host | Target triple for cross-compilation |
|
||
| `platform` | `"native"` | `native`, `efi` |
|
||
| `cflags` | `[]` | Additional C/C++/ASM flags |
|
||
| `ldflags` | `[]` | Additional linker flags |
|
||
| `filename` | `""` | Custom output file name |
|
||
| `extension` | `""` | Custom file extension (for `flat-bin`, default is `bin`) |
|
||
| `roots` | `["src"]` | Source roots: directories and/or individual source/header files |
|
||
| `exclude` | `[]` | Exclude patterns |
|
||
| `include` | `[]` | Additional include directories |
|
||
| `src_disable` | `false` | Disable auto source discovery |
|
||
| `inherit` | `false` | Inherit build from workspace root |
|
||
| `clean` | `[]` | Glob patterns for custom clean paths |
|
||
| `out_dir` | `""` | Custom output directory |
|
||
| `workspace_only` | `false` | Workspace-only, not built standalone (no `language`/`compiler` required) |
|
||
| `freestanding` | `false` | Compile in freestanding mode (`-ffreestanding` + `-nostdlib -static`) |
|
||
| `opt_level` | — | Optimization level: `0`-`3`, `"s"`, `"z"` (derived from profile if omitted) |
|
||
| `debug` | profile-based | Emit debug symbols (`-g`): `true` in debug, `false` in release |
|
||
| `lto` | `false` | Link-time optimization (`-flto` for both compiler and linker) |
|
||
| `strip` | `false` | Strip symbols from output (`-s` in ldflags) |
|
||
| `warnings` | `[]` | Warning flags (e.g. `"all"`, `"extra"`, `"pedantic"`); engine adds `-Wall -Wextra` in debug if empty |
|
||
| `panic` | `""` | Panic strategy: `"abort"` disables exceptions and unwind tables |
|
||
| `codegen-units` | `""` | Max parallel compilation jobs (`"0"` = auto) |
|
||
| `qt` | `false` | Enable automatic Qt meta-object handling (MOC, UIC, RCC) |
|
||
|
||
Settings from raw config (not in typed struct):
|
||
|
||
* `pkg_config` — list of packages queried for build-wide compiler/linker flags
|
||
|
||
Dependencies can also declare a system package directly, for example
|
||
`fmt = { pkg-config = "fmt" }`. This records the package in `dcr.lock` and applies
|
||
the flags returned by `pkg-config --cflags` and `pkg-config --libs`.
|
||
|
||
* `ldscript` — linker script path
|
||
* `build.steps` / `build.post_steps` — codegen steps
|
||
|
||
## Per-language overrides: `[build.c]`, `[build.cxx]`, `[build.asm]`, `[build.llvm_ir]`
|
||
|
||
Each language can have its own table that overrides the flat `[build]` settings:
|
||
|
||
```toml
|
||
[build]
|
||
compiler = "clang"
|
||
standard = "c11"
|
||
|
||
[build.c]
|
||
standard = "c23"
|
||
compiler = "gcc"
|
||
|
||
[build.cxx]
|
||
standard = "c++23"
|
||
compiler = "g++"
|
||
|
||
[build.asm]
|
||
compiler = "nasm"
|
||
flags = ["-felf64"]
|
||
|
||
[build.llvm_ir]
|
||
compiler = "llc"
|
||
```
|
||
|
||
The flat `[build]` acts as fallback; per-language tables take precedence for their language.
|
||
|
||
Example:
|
||
|
||
```toml
|
||
[build]
|
||
language = "c++"
|
||
standard = "c23"
|
||
cxx_standard = "c++23"
|
||
compiler = "clang"
|
||
kind = "sharedlib"
|
||
cflags = ["-Wall", "-Wextra"]
|
||
opt_level = "z"
|
||
lto = true
|
||
strip = true
|
||
panic = "abort"
|
||
codegen-units = "2"
|
||
```
|
||
|
||
## [toolchain]
|
||
|
||
```toml
|
||
[toolchain]
|
||
cc = "/usr/bin/clang"
|
||
cxx = "/usr/bin/clang++"
|
||
as = "/usr/bin/as"
|
||
ar = "/usr/bin/ar"
|
||
ld = "/usr/bin/ld.lld"
|
||
```
|
||
|
||
Raw config also supports `uic`, `moc`, `rcc` for Qt codegen.
|
||
|
||
## [dependencies]
|
||
|
||
See [dependencies](/docs/reference/dependencies).
|
||
|
||
## [run]
|
||
|
||
```toml
|
||
[run]
|
||
cmd = "./target/{profile}/{name}"
|
||
```
|
||
|
||
Substitutions:
|
||
|
||
* `{version}` — package version
|
||
* `{version_major}`, `{version_minor}`, `{version_patch}`, `{version_suffix}`, `{version_suffix_dash}` — version parts
|
||
* `{profile}` — debug / release
|
||
* `{name}` — package name
|
||
|
||
Default `cmd` = `./target/{profile}/{name}` (macOS/Windows) or `./target/\<triple>/\<profile>/\<name>` (Linux).
|
||
|
||
## [workspace]
|
||
|
||
See [workspaces](/docs/reference/workspaces).
|
||
|
||
## [archive]
|
||
|
||
Optional post-build step: format a FAT volume and copy built artifacts into a disk image. Runs after a successful package build (and after workspace member builds that define `[archive]`).
|
||
|
||
Requires DCR built with the `archive` Cargo feature (`cargo build --features archive`). Release binaries include this feature.
|
||
|
||
| Field | Required | Description |
|
||
| ------------ | -------- | ------------------------------------------------------------------------------------------- |
|
||
| `output` | yes | Image path relative to project root (`{profile}` allowed) |
|
||
| `format` | yes | `fat12`, `fat16`, or `fat32` |
|
||
| `size` | no | Image size: bytes or `K`/`KB`/`M`/`MB`/`G`/`GB` (default `1474560` ≈ 1.44 MiB) |
|
||
| `offset` | no | Byte offset of the FAT volume inside the image (default `0`) |
|
||
| `label` | no | Volume label (max 11 chars, default `VOLUME`) |
|
||
| `bootsector` | no | Path to a 512-byte boot sector written at offset 0 when `offset` is 0 (`{profile}` allowed) |
|
||
| `layout` | no | List of `{ from, to }` entries (files or globs → path inside the volume) |
|
||
|
||
```toml
|
||
[archive]
|
||
output = "target/{profile}/disk.img"
|
||
format = "fat12"
|
||
size = "1440K"
|
||
label = "MYOS"
|
||
bootsector = "target/{profile}/boot.bin"
|
||
|
||
[[archive.layout]]
|
||
from = "target/{profile}/kernel.bin"
|
||
to = "KERNEL.BIN"
|
||
|
||
[[archive.layout]]
|
||
from = "assets/*"
|
||
to = "/"
|
||
```
|
||
|
||
Typical pairing with `kind = "flat-bin"` (NASM `-f bin`) for bootloaders and pure-ASM OS images.
|
||
|
||
## `flat-bin` (kind)
|
||
|
||
Produces a raw binary (default extension `bin`) for boot sectors, kernels, and freestanding payloads.
|
||
|
||
### Assemblers
|
||
|
||
| Tool | Language / compiler | How flat-bin is produced |
|
||
| ---- | ------------------------------------------ | -------------------------------------------- |
|
||
| NASM | `language = "asm"`, `compiler = "nasm"` | `-f bin` → `\<stem>.bin` |
|
||
| FASM | `compiler = "fasm"` | direct write (use `format binary` in source) |
|
||
| GAS | `compiler = "as"` / `"gas"` | assemble → `objcopy -O binary` |
|
||
| MASM | `compiler = "ml"` / `"ml64"` | assemble → `objcopy -O binary` |
|
||
| LLC | `language = "llvm_ir"`, `compiler = "llc"` | `-filetype=obj` → `objcopy -O binary` |
|
||
|
||
```toml
|
||
[build]
|
||
language = "asm"
|
||
compiler = "nasm"
|
||
kind = "flat-bin"
|
||
extension = "bin"
|
||
roots = ["src/boot.asm"]
|
||
```
|
||
|
||
### C / C++
|
||
|
||
Compile all sources, link with `-nostdlib -static` (plus your `ldflags` / `ldscript`), then convert the intermediate ELF/PE with `objcopy -O binary` to `\<filename|name>.bin`.
|
||
|
||
```toml
|
||
[build]
|
||
language = "c"
|
||
compiler = "clang"
|
||
kind = "flat-bin"
|
||
freestanding = true
|
||
filename = "kernel"
|
||
extension = "bin"
|
||
ldscript = "linker.ld"
|
||
ldflags = ["-T", "linker.ld"]
|
||
```
|
||
|
||
Notes:
|
||
|
||
* Multi-file **ASM** packages emit one `\<stem>.bin` per source; **C/C++** emit a single project binary.
|
||
* `objcopy` tools tried in order: `llvm-objcopy`, `objcopy`, `gobjcopy`.
|
||
* Incompatible with `build.qt = true`.
|
||
* `dcr run` rejects `flat-bin` (not a host executable).
|