dexoron/dcr
1
1
Fork 0
mirror of https://github.com/dexoron/dcr.git synced 2026-10-21 13:28:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite documentation.

Browse Source 
add: Nix and Snapcraft support.
This commit is contained in:
Dexoron
2026-06-02 01:04:16 +08:00
parent c756d94f96
commit c42575e360
67 changed files with 1951 additions and 2295 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/commands/build-commands.mdx Normal file
View File

@@ -0,0 +1,42 @@
---
sidebar_label: Build commands (build, run, clean)
---
# Build Commands
## `dcr build`
Builds the project according to `dcr.toml`.
```bash
dcr build # debug profile
dcr build --release # release build
dcr build --debug # explicit debug
dcr build --target aarch64-unknown-linux-gnu
dcr build --force # full rebuild
dcr build --clean # clean + build
dcr build --verbose # show compilation commands
dcr build --workspace pkg-a # build specific workspace package
```
Artifacts: `target/<triple>/<profile>/<binary-name>` (Linux with explicit target).
## `dcr run`
Builds (if sources are newer than artifacts) and runs the binary.
```bash
dcr run
dcr run --release
```
## `dcr clean`
Removes `target/` directory (or `target/<target>/<profile>`).
```bash
dcr clean
dcr clean --release # target/release/ only
dcr clean --target windows # target/x86_64-pc-windows-msvc/
dcr clean --all # clean all workspace packages
```

37
docs/commands/dcr-add.md
View File

@@ -1,37 +0,0 @@
# dcr add
Add a dependency to `dcr.toml`.
## Usage
```bash
dcr add <name> [source] [options]
```
If `<source>` is omitted and a registry is configured, DCR will look up the
package by name in the registry and add it as a version dependency.
## Sources
- *omitted*: Look up in the configured registry.
- `path:./path/to/lib`: Local directory.
- `github:user/repo`: GitHub repository.
- `gitlab:user/repo`: GitLab repository.
- `git:host.com/user/repo`: Generic Git repository (HTTPS).
- `https://...`: Full Git URL.
## Options
- `--branch <name>`: Use a specific branch.
- `--tag <name>`: Use a specific tag.
- `--rev <sha>`: Use a specific commit hash.
## Examples
```bash
dcr add my_lib path:./libs/my_lib
dcr add cool_lib github:user/cool_lib
dcr add shared_lib gitlab:org/shared --branch develop
dcr add custom_lib git:git.internal.com/r/lib --tag v1.0.0
dcr add mylib # Looks up in registry
```

80
docs/commands/dcr-build.md
View File

@@ -1,80 +0,0 @@
# dcr build
Builds the project in `debug` or `release` profile.
## Usage
```sh
dcr build
dcr build --debug
dcr build --release
dcr build --target linux --release
dcr build --release --force
dcr build --debug --clean
```
## What `build` does
1. Checks that `dcr.toml` exists and is valid.
2. Reads build settings from `[build]`.
3. Resolves path dependencies from `[dependencies]`.
4. Creates required output directories.
5. Recursively compiles sources from `src/`.
6. Links final artifact (binary or library).
## Config values used
- `package.name`
- `build.filename`
- `build.extension`
- `build.compiler`
- `build.language`
- `build.standard`
- `build.cxx_standard`
- `build.kind`
- `build.target`
- `build.out_dir`
- `build.platform`
- `package.type`
- `build.cflags`
- `build.ldflags`
- `build.ldscript`
- `build.debug` / `build.release`
- `build.exclude`
- `build.include`
- `build.pkg_config`
- `build.steps`
- `build.post_steps`
- `build.generated`
- `build.expect`
- `build.clean`
## Source selection
- `language = "c"` -> `*.c`
- `language = "c++" | "cpp" | "cxx"` -> `*.cpp`, `*.cxx`, `*.cc`
- `language = "asm"` -> `*.s`, `*.S`, `*.asm`
- Mixed languages are supported with arrays, for example `language = ["c", "asm"]`.
- By default sources are searched in `src/`; use `build.roots` and `build.src_disable` to override.
## Notes
- Profile flag (`--debug` / `--release`) can appear in any argument position (duplicates are rejected).
- Unknown profile flags return an error.
- `--target <triple>` builds for specified target (short names: `linux`, `macos`, `windows`, `freebsd`, `openbsd`, `netbsd`).
- `--verbose` prints the compiler/linker command lines to stderr (also works via `DCR_DEBUG` env var).
- `--workspace <name>` filters build to a specific workspace member.
- If no `--target`, builds for `build.targets` or native.
- Incremental rebuild checks source/object mtime and tracked header dependencies.
- `--force` skips build cache checks and recompiles.
- `--clean` removes `target/<profile>` and `build.clean` paths before building.
- `build.filename` + `build.extension` allow full control over the final artifact name (e.g. `KERNEL.BIN` instead of using `package.name`). When `build.kind = "efi"`, the output is a PE32+ executable with `.efi` extension.
- `build.kind = "efi"` links with `-shared -nostdlib -Wl,-dll -Wl,--subsystem,10` for UEFI PE32+ format. Use `build.filename` and `build.extension` for full control over the artifact name.
- `build.kind = "elf"` produces a bare-metal ELF executable. Linking flags are user-controlled via `build.ldflags` (no PIE/CRT defaults are added).
- Default GCC/Clang profile flags: `debug` -> `-O0 -g -Wall -Wextra -fno-omit-frame-pointer -DDCR_DEBUG`, `release` -> `-O3 -DNDEBUG`.
These defaults are **not applied** for bare-metal targets (e.g. `aarch64-none-elf`, targets containing `none` / `-elf` / `eabi`).
- For `language = "asm"` with `compiler = "as"`/`"gas"`, use `.s` files (no preprocessing). For `.S`, use `gcc` or `clang`.
- In workspace root, `dcr build` builds all members in dependency order.
- `build.exclude` removes paths from source/header collection; `build.include` re-allows matching paths and has priority over `exclude`.
- `build.steps` run before compilation; `build.post_steps` run after linking.
- `build.generated` is cleaned when `build.steps` need to rerun; `build.expect` is verified after post-steps.

27
docs/commands/dcr-clean.md
View File

@@ -1,27 +0,0 @@
# dcr clean
Removes build artifacts in `target/`.
## Usage
```sh
dcr clean
dcr clean --debug
dcr clean --release
dcr clean --all
dcr clean --release --all
```
## Behavior
- Without arguments: removes entire `target/`.
- With profile: removes only the profile-specific directory. Respects `build.target` from config: if `build.target = "aarch64-unknown-linux-gnu"`, cleans `target/aarch64-unknown-linux-gnu/<profile>/`.
- With `--all`: also cleans all workspace members.
- Additionally removes paths from `build.clean` if configured.
- `build.clean` supports `{profile}` and version placeholders.
## Validation
- `dcr.toml` must exist.
- Unknown flags are treated as error.
- If `target` or selected profile directory does not exist, command prints a warning.

19
docs/commands/dcr-fmt.md
View File

@@ -1,19 +0,0 @@
# dcr fmt
Formats all C/C++ source files using `clang-format`.
## Usage
```sh
dcr fmt
```
## Behavior
1. Scans `src/` and `tests/` directories recursively.
2. Formats all C/C++ source and header files (`.c`, `.cpp`, `.cxx`, `.cc`, `.h`, `.hpp`, `.hxx`, `.hh`) using `clang-format`.
3. Uses `.clang-format` if present in the project root, otherwise falls back to LLVM style.
## Requirements
- `clang-format` must be installed and available in PATH.

170
docs/commands/dcr-gen.md
View File

@@ -1,170 +0,0 @@
# dcr gen
Generates IDE and build tool integration files for C/C++ development environments.
## Usage
```sh
dcr gen project-info
dcr gen project-info --release
dcr gen compile-commands
dcr gen compile-commands --debug
dcr gen vscode
dcr gen vscode --release
dcr gen clion
dcr gen clion --debug
```
## Subcommands
### `dcr gen project-info`
Outputs project metadata as JSON array.
```sh
dcr gen project-info [--debug | --release]
```
Outputs structured information about the project (root project + all workspace members if present):
```json
[
{
"name": "my-project",
"version": "1.0.0",
"root": "/path/to/root",
"profile": "debug",
"language": "c++",
"standard": "c++17",
"compiler": "g++",
"kind": "bin",
"sources": ["/path/to/root/src/main.cpp", ...],
"include_dirs": ["/path/to/dep/include", ...],
"lib_dirs": ["/path/to/dep/lib", ...],
"libs": ["somelib", ...],
"cflags": ["-Wall", ...],
"ldflags": ["-lm", ...]
}
]
```
This is useful for integrating DCR projects with custom build tools or scripts.
### `dcr gen compile-commands`
Generates `compile_commands.json` for use by `clangd`, `clang-tidy`, and other tools.
```sh
dcr gen compile-commands [--debug | --release]
```
Writes `./compile_commands.json` containing compilation database entries for all source files. This file is recognized by:
- LSP servers (`clangd`, `clang-tools-extra`)
- Linters (`clang-tidy`)
- Format tools (`clang-format`)
The entries include:
- Full compiler command with flags
- Source file path
- Object file output path
- Project root as working directory
### `dcr gen vscode`
Generates Visual Studio Code integration files.
```sh
dcr gen vscode [--debug | --release]
```
Creates `.vscode/` directory with:
- **`launch.json`**: Debug configurations (one per binary target, debug + release variants)
- **`tasks.json`**: Build/run/clean tasks using `dcr` commands
- **`settings.json`**: Clangd configuration pointing to `compile_commands.json`
- **`extensions.json`**: Recommends `clangd`, disables `cpptools`
- **`compile_commands.json`**: Compilation database (same as `dcr gen compile-commands`)
Usage in VSCode:
- Open the Command Palette (`Ctrl+Shift+P`) and select **"Debug: Start Debugging"** to run debugger
- Press `Ctrl+Shift+B` to run the build task
- Clangd will provide IntelliSense and diagnostics based on `compile_commands.json`
- Generated `launch.json` uses CodeLLDB (`type: "lldb"`), so install `vadimcn.vscode-lldb`
### `dcr gen clion`
Generates JetBrains CLion integration files.
```sh
dcr gen clion [--debug | --release]
```
Creates `.idea/` directory with:
- **`externalTools.xml`**: Registers DCR build/clean/gen commands as external tools
- **`customTargets.xml`**: Defines build targets for debug and release
- **`misc.xml`**: Points CLion to `compile_commands.json` for compilation database
- **`.idea/.gitignore`**: Ignores auto-generated files
- **`runConfigurations/*.xml`**: Debug run configs (one per binary target)
- **`compile_commands.json`**: Compilation database (same as `dcr gen compile-commands`)
Usage in CLion:
- Build/clean via **Tools → DCR → Build Debug/Release/Clean**
- Run/debug via **Run → Run Configurations** (dropdown) → select generated config
- Code completion and diagnostics come from the compilation database
## Config values used
- `package.name`
- `build.compiler`
- `build.language`
- `build.standard`
- `build.kind`
- `build.target`
- `build.platform`
- `build.cflags`
- `build.ldflags`
- `build.debug` / `build.release`
- `build.exclude`
- `build.include`
- `build.pkg_config`
- `build.roots`
- `build.src_disable`
- Workspace members (if `[workspace]` is present)
## Workspace support
When running `dcr gen` in a workspace root, all commands process both the root project and all workspace members:
- `project-info` returns an array with entries for each member + root
- `compile-commands` includes entries from all members
- `vscode` and `clion` generate unified configurations that work across all members
## Troubleshooting
### Clangd not picking up includes
- Ensure `compile_commands.json` exists in the workspace root
- In VSCode settings, verify `clangd.arguments` includes `--compile-commands-dir=<workspace-root>`
- Rebuild via `dcr gen compile-commands` if sources or dependencies changed
### Debug configuration not working
- Verify binary paths in `launch.json` match actual build output (`target/<profile>/binary-name`)
- For workspace projects, each member's debug config uses its own `target/` directory
- Ensure GDB/LLDB is installed: `gdb --version` or `lldb --version`
- If VSCode reports unsupported debugger type, install the extension that matches `launch.json` type (`vadimcn.vscode-lldb` for `lldb`)
### CLion not recognizing includes
- Regenerate via `dcr gen clion --debug`
- File → Invalidate Caches → Invalidate and Restart
- Verify `.idea/misc.xml` points to correct `compile_commands.json` path
## Notes
- Profiles default to `debug` if not specified
- Generation does not require the project to be built first
- Generated files are safe to commit; they are generated from `dcr.toml` and thus repeatable
- IDE configurations may be customized after generation, but changes will be overwritten on next `dcr gen` run
- For multi-binary projects, `vscode` and `clion` generate debug configs for all binaries (both debug + release variants)

43
docs/commands/dcr-init-or-new.md
View File

@@ -1,43 +0,0 @@
# dcr init/new
## `dcr new <name>`
Creates a new project directory and initializes it.
```sh
dcr new hello
```
Behavior:
1. Validates arguments (`<name>` is required, only one name is allowed).
2. Creates `<name>/`.
3. Creates `<name>/dcr.toml`.
4. Sets `package.name = "<name>"`.
5. Creates `<name>/src/main.c` with a Hello World template.
Errors:
- Missing project name.
- Extra arguments.
- Target directory already exists.
## `dcr init`
Initializes DCR in the current directory.
```sh
dcr init
```
Behavior:
1. Requires current directory to be empty.
2. Creates `dcr.toml`.
3. Sets `package.name` from the current directory name.
4. Creates `src/main.c`.
Errors:
- Any arguments are treated as invalid.
- Non-empty directory is rejected.

41
docs/commands/dcr-run.md
View File

@@ -1,41 +0,0 @@
# dcr run
Builds the project and runs the resulting binary.
## Usage
```sh
dcr run
dcr run --debug
dcr run --release
dcr run --target linux --release
dcr run --release --force
dcr run --debug --clean
```
## Behavior
1. Validates `dcr.toml`.
2. Reads `package.name`, `build.kind`, and optional `build.target`.
3. Runs the same build flow as `dcr build`.
4. Executes the built artifact path for the selected profile.
5. If `[run].cmd` is set, runs that command instead of the built binary.
## Restrictions
- If `build.kind` (or `build.{profile}.kind`) is `"staticlib"`, `"sharedlib"`, `"efi"`, or `"elf"`, `run` exits with error.
- The profile is selected from the first argument.
- `--target <triple>` runs the binary for specified target (short names: `linux`, `macos`, `windows`, `freebsd`, `openbsd`, `netbsd`).
- `--force` skips build cache checks and recompiles.
- `--clean` removes `target/<profile>` and `build.clean` paths before building.
- `--workspace <name>` filters build to a specific workspace member.
## `run.cmd` variables
`run.cmd` supports the same variables as build steps: `{profile}`, `{version}`, `{version_major}`,
`{version_minor}`, `{version_patch}`, `{version_suffix}`, `{version_suffix_dash}`.
The command runs via `sh -c` on Unix and `cmd /C` on Windows.
## On build failure
`dcr run` attempts to launch an existing binary from the same profile if present; otherwise it reports that code errors must be fixed.

45
docs/commands/dcr-test.md
View File

@@ -1,45 +0,0 @@
# dcr test
Runs the project's test suite.
## Usage
```sh
dcr test
dcr test --debug
dcr test --release
dcr test --target linux
dcr test --init
```
## What `test` does
1. Builds the project with the specified profile/target.
2. Compiles test files in `tests/` (e.g., `tests/test.c`) into a test binary.
3. Runs the test binary and parses output for PASS/SKIP/FAIL results.
4. Reports summary with colored output.
## Test Structure
DCR uses a simple test framework:
- Header: `tests/dcr_test.h` (generated by `dcr test --init`)
- Test file: `tests/test.c` (template generated by `dcr test --init`)
- Macros: `TEST(name)`, `TEST_CASE(name)`, `EXPECT(condition)`, `SKIP(reason)`
- Output: `[PASS] test_name`, `[FAIL] test_name`, or `[SKIP] test_name`
## Config values used
- `package.name`
- `build.compiler`, `build.language`, `build.standard`
- `build.cflags`, `build.ldflags`
- `build.debug` / `build.release`
- `build.targets` (if specified)
## Notes
- Test binary is linked with the main project (for lib projects) or standalone.
- `--init` creates `tests/dcr_test.h` and `tests/test.c` if missing.
- Tests run in debug mode by default. Use `--release` for release mode.
- Custom test logic can be added by editing `tests/test.c`.
- Fails if no `tests/test.c` exists (run `dcr test --init` first).

22
docs/commands/dcr-tree.md
View File

@@ -1,22 +0,0 @@
# dcr tree
Displays a visual dependency tree for the current project (similar to `cargo tree`).
## Usage
```sh
dcr tree
dcr tree --invert
dcr tree -p some-package
```
## What it shows
- All direct and transitive dependencies
- Version of each dependency
- Whether a dependency is a registry, git, or path dependency
## Notes
- Useful for debugging dependency issues and understanding the build graph.
- Output format is inspired by `cargo tree`.

51
docs/commands/dependency-commands.mdx Normal file
View File

@@ -0,0 +1,51 @@
---
sidebar_label: Dependency commands (add, tree)
---
# Dependency Commands
## `dcr add <name> [source]`
Adds a dependency to `dcr.toml`.
```bash
dcr add fmt # registry lookup
dcr add mylib ../path/to/lib # path as source
dcr add mylib path:./lib # explicit path prefix
dcr add mylib git:https://github.com/user/repo # explicit git prefix
dcr add mylib github:user/repo # GitHub shorthand
dcr add mylib gitlab:user/repo # GitLab shorthand
```
Source prefixes:
- `path:` — local path
- `git:` — generic git URL
- `github:` — expands to `https://github.com/<user>/<repo>`
- `gitlab:` — expands to `https://gitlab.com/<user>/<repo>`
- `http://` / `https://` / `git@` — full URL
Flags:
- `--branch <name>` — git branch
- `--tag <name>` — git tag
- `--rev <hash>` — git commit
If source is omitted — DCR searches connected registries.
## `dcr tree`
Displays the project dependency tree.
```bash
dcr tree
```
Example output:
```
my-app v0.1.0
├── fmt (registry)
│ └── spdlog (registry)
└── catch2 (registry)
```
For path dependencies, recursively shows their own dependencies (from their `dcr.toml`).

71
docs/commands/gen-commands.mdx Normal file
View File

@@ -0,0 +1,71 @@
---
sidebar_label: Gen commands (vscode, clion, ...)
---
# Gen Commands
## `dcr gen <target>`
Generates IDE integration files.
### vscode
```bash
dcr gen vscode
```
Creates:
- `.vscode/tasks.json` — `build` task (dcr build)
- `.vscode/launch.json` — debug launch configuration
- `.vscode/settings.json` — C/C++ settings (clangd paths, includes)
- `.vscode/extensions.json` — recommended extensions (vscode-clangd, vscode-lldb)
### clion
```bash
dcr gen clion
```
Creates:
- `.idea/externalTools.xml` — external tools (build, run, clean, test)
- `.idea/customTargets.xml` — custom build targets
- `.idea/misc.xml` — C/C++ project settings
- `.idea/runConfigurations/<name>.xml` — per-binary run configurations
### compile-commands
```bash
dcr gen compile-commands
```
Generates `compile_commands.json` — standard format for clangd, cpptools, static analyzers.
### project-info
```bash
dcr gen project-info
```
Outputs JSON array with project metadata:
```json
[
{
"name": "my-app",
"version": "0.1.0",
"root": "/path/to/project",
"profile": "debug",
"language": "c",
"standard": "c17",
"cxx_standard": null,
"compiler": "/usr/bin/clang",
"kind": "bin",
"sources": ["src/main.c"],
"include_dirs": ["src"],
"lib_dirs": [],
"libs": [],
"cflags": ["-std=c17", "-O0", "-g"],
"ldflags": []
}
]
```

44
docs/commands/global-options.md
View File

@@ -1,44 +0,0 @@
# Global options
## `dcr --help`
```sh
dcr --help
```
Prints top-level CLI usage, commands, flags, and examples.
## `dcr --version`
```sh
dcr --version
```
Prints:
```text
dcr <version> (<target>)
```
## `dcr --update`
```sh
dcr --update
```
Update flow:
1. Requests latest release from GitHub API.
2. Finds asset matching current `DCR_TARGET`.
3. Downloads replacement binary.
4. Replaces current executable via `self-replace`.
Limitations and behavior:
- No extra arguments are accepted.
- Requires network access to GitHub API/assets.
- On Linux, if binary is owned by pacman, DCR prints package-manager update instructions instead of self-updating.
## Running without command
Running plain `dcr` (without arguments) shows help output.

28
docs/commands/project-commands.mdx Normal file
View File

@@ -0,0 +1,28 @@
---
sidebar_label: Project commands (new, init)
---
# Project Commands
## `dcr new <name>`
Creates a new project with a standard structure and `dcr.toml`. The `name` argument is required.
```bash
dcr new my-app
```
Generates:
- `dcr.toml` with basic fields
- `src/main.c` with a `main` template
## `dcr init`
Initializes a DCR project in the current (empty) directory.
```bash
mkdir app && cd app
dcr init
```
The project name is taken from the current directory name.

44
docs/commands/quality-commands.mdx Normal file
View File

@@ -0,0 +1,44 @@
---
sidebar_label: Quality commands (test, fmt)
---
# Quality Commands
## `dcr test`
Runs tests.
```bash
dcr test # debug profile
dcr test --release # release profile
dcr test --debug # explicit debug
dcr test --help # detailed help
```
Before first use, initialize tests:
```bash
dcr test --init
```
This creates `tests/dcr_test.h` (framework) and `tests/test.c` (template).
What `dcr test` does:
1. Builds the project
2. Collects `tests/*.c` files (`.c` only, not `.cpp`)
3. Compiles and links each test file
4. Runs each test binary
5. Prints summary: TOTAL, PASS, SKIP, FAIL
6. Returns non-zero exit code on any FAIL
## `dcr fmt`
Formats C/C++ source files using `clang-format`.
```bash
dcr fmt
```
Processes: `src/**/*.{c,cpp,cxx,cc,h,hpp,hxx,hh}` and `tests/**/*.{c,cpp,cxx,cc,h,hpp,hxx,hh}`.
Uses `.clang-format` at the project root (if present), otherwise default clang-format style.

50
docs/commands/system-commands.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
sidebar_label: System commands (setup, --help, ...)
---
# System Commands
## `dcr setup`
Shows configured registries from `~/.dcr/config.toml`.
```bash
dcr setup
```
If `~/.dcr/config.toml` is not found, DCR returns an error. Create it manually:
```toml
[[registry]]
name = "default"
url = "https://index.dcr.pm"
```
## `dcr --help`
Shows help for all commands.
```bash
dcr --help
```
## `dcr --version`
Shows version and target triple.
```bash
dcr --version # dcr 0.7.0 (x86_64-unknown-linux-gnu)
```
## `dcr --update`
Self-update. Downloads the latest release binary from GitHub Releases and replaces the current one.
```bash
dcr --update
```
Features:
- Auto-detects platform and architecture
- Warns if installed via AUR (use package manager instead)
- Works on Linux, macOS, Windows