docs: rewrite documentation.

add: Nix and Snapcraft support.
2026-10-21 09:28:35 +00:00 · 2026-06-02 01:04:16 +08:00
parent c756d94f96
commit c42575e360
67 changed files with 1951 additions and 2295 deletions
--- a/docs/reference/build-profiles.mdx
+++ b/docs/reference/build-profiles.mdx
@@ -0,0 +1,55 @@
+---
+sidebar_label: Build profiles
+---
+
+# Build Profiles
+
+Profiles allow overriding `[build]` fields for specific build modes.
+
+## Configuration
+
+```toml
+[build]
+language = "c"
+standard = "c17"
+cflags = ["-Wall"]
+
+[build.debug]
+cflags = ["-O0", "-g"]
+
+[build.release]
+cflags = ["-O3", "-DNDEBUG"]
+```
+
+## Merge rules
+
+Fields from `[build.<profile>]` are merged on top of `[build]`:
+
+- **Scalar fields** (strings, numbers, bools) — replaced
+- **Arrays** (`cflags`, `ldflags`, ...) — **appended** (extend the `[build]` array)
+
+Set `inherit = false` to disable array inheritance (only profile's own arrays are used).
+
+## Built-in profiles
+
+| Profile | Default cflags |
+|---------|---------------|
+| `debug` | `-O0 -g -Wall -Wextra -fno-omit-frame-pointer -DDCR_DEBUG` |
+| `release` | `-O3 -DNDEBUG` |
+
+## Target-specific profiles
+
+```toml
+[build.linux]
+cflags = ["-DLINUX"]
+
+[build.windows.debug]
+cflags = ["-DWIN32", "-O0", "-g"]
+```
+
+Application order (highest priority first):
+1. `[build.<target>.<profile>]`
+2. `[build.<profile>.<target>]`
+3. `[build.<target>]`
+4. `[build.<profile>]`
+5. `[build]`
--- a/docs/reference/build-system.mdx
+++ b/docs/reference/build-system.mdx
@@ -0,0 +1,101 @@
+---
+sidebar_label: Build system
+---
+
+# Build System
+
+## Compiler Backends
+
+DCR supports 4 compilation backends. Selection is automatic based on file extension.
+
+| Backend | Files | When used |
+|---------|-------|-----------|
+| `unix_cc` | `.c`, `.cpp`, `.cxx`, `.cc`, `.S` | gcc/clang on Linux/macOS/BSD |
+| `msvc` | `.c`, `.cpp`, `.cxx`, `.cc` | Windows (cl, clang-cl) |
+| `gas` | `.s` | ARM/ARM64 assembler (no preprocessor) |
+| `nasm` | `.asm` | x86/x86_64 assembler |
+
+### Unix CC
+
+- Compiler resolved via `resolve_compiler()`: `DCR_COMPILER` > `DCR_CC` > `[toolchain]` > `build.compiler` > `PATH`
+- Supports `.d` files for header dependency tracking
+- Flags: `-std=`, `-MMD -MF`, `-c -o`, `-I`, `-L`, `-l`
+
+### MSVC
+
+- Supports cl.exe and clang-cl.exe
+- Flags: `/std:`, `/Fo:`, `/Fe:`, `/I`, `/link`
+
+### GAS / NASM
+
+- GAS: `-I`, `-c -o`, `--defsym`
+- NASM: `-I`, `-o`, `-D`, `-f` (format: win64/elf64/macho64/macho32/elf32)
+
+## Incremental Builds
+
+Three levels of incrementality:
+
+1. **mtime** — if output is newer than all inputs, skip
+2. **`.d` files** — header change tracking (including transitive)
+3. **SHA256 fingerprint** — recompile if compiler flags changed (stored in `.dcr_fingerprint`)
+
+## Parallel Compilation
+
+- `thread::scope` for thread pool
+- Atomic task queue (`AtomicU64`)
+- Mutex on stdout (`OUTPUT_MUTEX`)
+- Thread count = `available_parallelism()`
+
+## Build Kinds
+
+| Kind | Type | Path (Linux example) |
+|------|------|---------------------|
+| `bin` | Executable | `target/<triple>/<profile>/<name>` (.exe on Windows) |
+| `staticlib` | Static library | `target/<triple>/<profile>/lib<name>.a` (.lib) |
+| `sharedlib` | Dynamic library | `target/<triple>/<profile>/lib<name>.so` (.dll/.dylib) |
+| `efi` | UEFI application | `target/<triple>/<profile>/<name>.efi` |
+| `elf` | ELF without stdlib | `target/<triple>/<profile>/<name>` |
+| `none` | Compile only, no link | — |
+| `custom` | Full filename+extension control | `target/<triple>/<profile>/<filename>.<extension>` |
+
+## Build Steps
+
+DCR supports pre-build and post-build steps:
+
+- `build.steps` — commands before compilation
+- `build.post_steps` — commands after compilation
+
+Substitutions: `{stem}`, `{in}`, `{out}`, `{profile}`, `{version}`, `{name}`.
+
+Example Qt codegen via build steps:
+
+```toml
+[build.steps]
+moc = "moc {in} -o {out}"
+```
+
+## pkg-config
+
+Automatic lookup (read from raw config):
+
+```toml
+[build]
+pkg_config = ["sdl2", "gl"]
+```
+
+DCR runs `pkg-config --cflags sdl2 gl` and `pkg-config --libs sdl2 gl` and adds results to compiler/linker flags.
+
+## Variable Substitution
+
+Supported variables:
+
+| Variable | Description |
+|----------|-------------|
+| `{version}` | Package version |
+| `{version_major}` | Major version part |
+| `{version_minor}` | Minor version part |
+| `{version_patch}` | Patch version |
+| `{version_suffix}` | Suffix (e.g., `-rc1`) |
+| `{version_suffix_dash}` | Suffix with dash |
+| `{profile}` | Profile name (debug/release) |
+| `{name}` | Package name |
--- a/docs/reference/cross-compilation.mdx
+++ b/docs/reference/cross-compilation.mdx
@@ -0,0 +1,60 @@
+---
+sidebar_label: Cross-compilation
+---
+
+# Cross-Compilation
+
+## Short Names
+
+DCR supports short platform names:
+
+| Short Name | Full Triple |
+|-----------|-------------|
+| `linux` | `x86_64-unknown-linux-gnu` |
+| `macos` | `x86_64-apple-darwin` |
+| `windows` | `x86_64-pc-windows-msvc` |
+
+```bash
+dcr build --target windows
+```
+
+## Full Triples
+
+```bash
+dcr build --target aarch64-unknown-linux-gnu
+dcr build --target x86_64-pc-windows-gnu      # mingw
+dcr build --target armv7-unknown-linux-gnueabihf
+```
+
+## clang --target
+
+When using clang, DCR injects `--target=<triple>` into CFLAGS.
+
+```toml
+[build]
+compiler = "clang"
+target = "aarch64-unknown-linux-gnu"
+# Auto: cflags += ["--target=aarch64-unknown-linux-gnu"]
+```
+
+## Bare-Metal
+
+For targets containing `none`, `-elf`, `eabi`, or `baremetal`, DCR default flags are disabled (no system include paths, no `-l` libc).
+
+```bash
+dcr build --target aarch64-none-elf
+```
+
+## Target Directory
+
+On Linux with explicit target:
+
+```
+target/<triple>/<profile>/
+```
+
+On macOS/Windows or without target:
+
+```
+target/<profile>/
+```
--- a/docs/reference/dcr-toml.mdx
+++ b/docs/reference/dcr-toml.mdx
@@ -0,0 +1,132 @@
+---
+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
+```
+
+## [package]
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Project name |
+| `version` | yes | Semantic version |
+| `type` | yes | `app`, `lib`, `none` |
+| `license` | no | SPDX license identifier |
+| `author` | no | Author |
+
+```toml
+[package]
+name = "my-app"
+version = "0.1.0"
+type = "app"
+license = "MIT"
+author = "John Doe"
+```
+
+## [build]
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `language` | `"c"` | `"c"`, `"c++"`, `"cpp"`, `"cxx"`, `"asm"` |
+| `standard` | `"c11"` | C standard (`c11`, `c17`, `c23`) |
+| `cxx_standard` | `"c++20"` | C++ standard (`c++17`, `c++20`, `c++23`) |
+| `compiler` | `"clang"` | Preferred compiler |
+| `kind` | `"bin"` | `bin`, `staticlib`, `sharedlib`, `efi`, `elf`, `none`, `custom` |
+| `target` | host | Target triple for cross-compilation |
+| `platform` | `"native"` | `native`, `efi`, `freestanding` |
+| `cflags` | `[]` | Additional C/C++/ASM flags |
+| `ldflags` | `[]` | Additional linker flags |
+| `filename` | `""` | Custom output file name |
+| `extension` | `""` | Custom file extension |
+| `roots` | `["src"]` | Source root directories |
+| `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 |
+
+Settings from raw config (not in typed struct):
+- `pkg_config` — list of pkg-config packages
+- `ldscript` — linker script path
+- `build.steps` / `build.post_steps` — codegen steps
+
+Example:
+
+```toml
+[build]
+language = "c++"
+standard = "c23"
+cxx_standard = "c++23"
+compiler = "clang"
+kind = "sharedlib"
+cflags = ["-Wall", "-Wextra"]
+```
+
+## [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).
--- a/docs/reference/dependencies.mdx
+++ b/docs/reference/dependencies.mdx
@@ -0,0 +1,84 @@
+---
+sidebar_label: Dependencies
+---
+
+# Dependencies
+
+## Formats
+
+The `[dependencies]` section supports three formats:
+
+### String (registry)
+
+```toml
+[dependencies]
+fmt = "10.1.1"
+spdlog = "1.12"
+catch2 = "3.4.0"
+```
+
+The version string is used as-is for registry lookup.
+
+### Table (git)
+
+```toml
+[dependencies]
+fmt = { git = "https://github.com/fmtlib/fmt", tag = "10.1.1" }
+```
+
+Fields: `git`, `branch`, `tag`, `rev`.
+
+### Table (path)
+
+```toml
+[dependencies]
+mylib = { path = "../mylib" }
+```
+
+## Registry
+
+DCR uses a package registry for dependency lookup by name.
+
+```toml
+# ~/.dcr/config.toml
+[[registry]]
+name = "default"
+url = "https://index.dcr.pm"
+```
+
+Registry priority: order in `config.toml`. The `DCR_INDEX_PATH` variable overrides the path to `index.json`.
+
+## Git dependencies
+
+DCR clones git repositories via `git2`:
+
+- `branch` — switch to a branch
+- `tag` — switch to a tag
+- `rev` — switch to a specific commit
+- `features` — feature flags (parsed, but does not affect build)
+
+Cache path: `~/.dcr/git/<hash>/`.
+
+## Path dependencies
+
+Local paths. DCR automatically discovers include and lib directories from the neighbor's `dcr.toml`.
+
+```toml
+[dependencies]
+mylib = { path = "/abs/path/to/lib" }
+mylib = { path = "../relative/path" }
+```
+
+## dcr.lock
+
+Dependency lock file. Contains package names and sources.
+
+Created during `dcr build` when registry dependencies are present. Not updated during `dcr add` — only on the next `dcr build`.
+
+## Resolution process
+
+1. Load all dependencies (registry → git → path)
+2. For path deps: recursively read their `dcr.toml`
+3. For registry deps: search `index.json`
+4. For git deps: clone to cache
+5. Collect `include_dirs`, `lib_dirs`, `libs` for the compiler
--- a/docs/reference/environment-variables.mdx
+++ b/docs/reference/environment-variables.mdx
@@ -0,0 +1,59 @@
+---
+sidebar_label: Environment variables
+---
+
+# Environment Variables
+
+## DCR_COMPILER
+
+Overrides the compiler for all languages. **Highest priority.**
+
+```bash
+export DCR_COMPILER=clang
+dcr build
+```
+
+Compiler resolution priority:
+1. `DCR_COMPILER` (env)
+2. `DCR_CC` / `DCR_CXX` / `DCR_AS` (env)
+3. `[toolchain]` (dcr.toml)
+4. `build.compiler` (dcr.toml)
+5. `PATH`
+
+## DCR_CC / DCR_CXX / DCR_AS
+
+Per-language override (lower priority than `DCR_COMPILER`, higher than `[toolchain]`).
+
+```bash
+export DCR_CC=gcc-14
+export DCR_CXX=g++-14
+export DCR_AS=arm-linux-gnueabihf-as
+```
+
+## DCR_LD / DCR_AR
+
+Override linker and archiver.
+
+```bash
+export DCR_LD=ld.lld
+export DCR_AR=llvm-ar
+```
+
+## DCR_DEBUG
+
+Enables debug mode — prints all compilation commands to stderr before execution.
+
+```bash
+export DCR_DEBUG=1
+dcr build
+```
+
+## DCR_INDEX_PATH
+
+Overrides the path to the registry `index.json`.
+
+```bash
+export DCR_INDEX_PATH=/custom/path/index.json
+```
+
+Default: `~/.dcr/index.json`.
--- a/docs/reference/platform-support.mdx
+++ b/docs/reference/platform-support.mdx
@@ -0,0 +1,51 @@
+---
+sidebar_label: Platform support
+---
+
+# Platform Support
+
+## Target Triples
+
+DCR normalizes target triples. Short platform names are expanded to full triples.
+
+### Linux
+
+```
+target/<arch>-unknown-linux-gnu/<profile>/
+```
+
+Architectures: `x86_64`, `aarch64` (host-detected).
+
+Artifact type: ELF. Extensions: `.so` (sharedlib), `.a` (staticlib).
+
+### macOS
+
+```
+target/<profile>/
+```
+
+Architectures: `x86_64`, `aarch64` (host-detected).
+
+Extensions: `.dylib` (sharedlib), `.a` (staticlib).
+
+### Windows
+
+```
+target/<profile>/
+```
+
+Architectures: `x86_64`, `aarch64`.
+
+Extensions: `.exe` (bin), `.lib` (staticlib), `.dll` (sharedlib), `.efi` (UEFI).
+
+### BSD
+
+```
+target/<arch>-unknown-<os>/<profile>/
+```
+
+Supported systems: `freebsd`, `openbsd`, `netbsd`, `dragonfly`.
+
+## Host Detection
+
+DCR uses `std::env::consts::ARCH` and `std::env::consts::OS` for host platform detection. Used as fallback when `target` is not specified.
--- a/docs/reference/workspaces.mdx
+++ b/docs/reference/workspaces.mdx
@@ -0,0 +1,67 @@
+---
+sidebar_label: Workspaces
+---
+
+# Workspaces
+
+Workspaces allow managing multiple packages in a single repository.
+
+## Configuration
+
+```toml
+[workspace.lib-core]
+path = "lib-core"
+
+[workspace.lib-utils]
+path = "lib-utils"
+deps = ["lib-core"]
+
+[workspace.app]
+path = "app"
+deps = ["lib-core", "lib-utils"]
+main = true
+```
+
+### Member fields
+
+| Field | Description |
+|-------|-------------|
+| `path` | Path to the package (relative to workspace root) |
+| `deps` | Dependencies on other members |
+| `main` | Mark as the main package |
+
+## Topological sort
+
+DCR automatically sorts packages by dependencies: package A is built before B if B depends on A.
+
+Cyclic dependencies are detected and cause an error.
+
+## Build
+
+```bash
+dcr build                    # build all packages in dependency order
+dcr build --workspace app    # build only app (dependencies built automatically)
+```
+
+When building a workspace, member outputs (libraries) are automatically added to include/lib paths of dependent packages.
+
+## Clean
+
+```bash
+dcr clean                    # clean only root target/
+dcr clean --all              # clean target/ of all packages
+```
+
+## Inheritance
+
+If a member has `inherit = true` in its `[build]` section, fields from the root `[build]` are merged into the member:
+
+```toml
+# root dcr.toml
+[build]
+inherit = true
+language = "c"
+standard = "c17"
+
+# member inherits language and standard
+```