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

New docs

Browse Source
This commit is contained in:
Dexoron
2026-02-26 18:09:07 +08:00
parent 83061cc460
commit c22d2dbddc
31 changed files with 781 additions and 431 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs-old/dcr-toml.md
View File

@@ -1,63 +0,0 @@
# dcr.toml
`dcr.toml` describes your project, build options, and dependencies.
## Example
```toml
[package]
name = "neoarc-frontent"
version = "0.1.0"
[build]
language = "c"
standard = "c11"
compiler = "gcc"
# Build kind: "bin" (default) or "staticlib"
kind = "bin"
# Output directory for binary (optional)
target = "./dist"
# Custom compile/link flags (optional)
cflags = ["-D_POSIX_C_SOURCE=200809L", "-Wall", "-Wextra", "-O2", "-Ilib/frecli"]
ldflags = ["-Llib/frecli", "-lfrecli", "-lm"]
[dependencies]
frecli = { path = "./lib/frecli", include = ["."], lib = ["."], libs = ["frecli"] }
```
## Sections
### [package]
- `name` (string, required)
- `version` (string, required)
### [build]
- `language` (string, required): `c`, `c++`, `cpp`, or `cxx`
- `standard` (string, required): e.g. `c99`, `c11`, `c++17`
- `compiler` (string, required): `gcc`, `clang`, `cl`(msvc), or `clang-cl`
- `kind` (string, optional): `bin` (default) or `staticlib`
- `target` (string, optional): output directory for the binary (profile-independent)
- `cflags` (string[], optional): additional compile flags
- `ldflags` (string[], optional): additional link flags
Notes:
- `dcr run` is supported only for `kind = "bin"`.
- Incremental rebuild currently tracks source file changes (`.c/.cpp`) only.
### [dependencies]
Only `path` dependencies are supported right now.
```toml
[dependencies]
fmt = { path = "./lib/fmt", include = ["include"], lib = ["lib"], libs = ["fmt"] }
```
Rules:
- `path` can be absolute or relative to the project root.
- If `include`/`lib` are missing, DCR looks for `include`, `lib`, or `lib64` under the dependency path.
- If not found, build fails with a message suggesting to add `include`/`lib`.
- `libs` defaults to the dependency name.
## Source Discovery
DCR compiles all `.c`/`.cpp` files under `src/` recursively. The file containing `main()` can be located anywhere in that tree.

48
docs-old/index.md
View File

@@ -1,48 +0,0 @@
# DCR Documentation
DCR is a lightweight build tool for C/C++ projects with a Cargo-like workflow.
## Quick Start
```sh
dcr new hello
cd hello
dcr run
```
## Configuration
Project configuration lives in `dcr.toml`.
See `docs/dcr-toml.md` for the full schema and examples.
## Build Flags
You can add custom compile and link flags in `[build]`:
```toml
[build]
compiler = "gcc"
standard = "c99"
kind = "bin"
target = "./dist"
cflags = ["-D_POSIX_C_SOURCE=200809L", "-Wall", "-Wextra", "-O2", "-Ilib/frecli"]
ldflags = ["-Llib/frecli", "-lfrecli", "-lm"]
```
## Dependencies
Path dependencies can be declared in `[dependencies]` and are resolved on build.
```toml
[dependencies]
frecli = { path = "./lib/frecli", include = ["."], lib = ["."], libs = ["frecli"] }
```
## Source Discovery
DCR compiles all `.c`/`.cpp` files under `src/` recursively. The file containing `main()` can be in any subdirectory.
## Notes
- `dcr run` works only for `kind = "bin"`.
- Incremental rebuild currently tracks source file changes only (`.c/.cpp`).

57
docs-old/ru/CONTRIBUTING_ru.md
View File

@@ -1,57 +0,0 @@
# Вклад в проект
Спасибо за интерес к проекту.
## Требования
- Использовать Rust stable.
- Перед PR код должен проходить форматирование, линт и сборку.
## Быстрый старт
```bash
git clone https://github.com/dexoron/dcr.git
cd dcr
cargo check
```
## Стиль кода
- Форматируйте код через `cargo fmt`.
- Проверяйте предупреждения через `cargo clippy`.
- Держите функции небольшими и сфокусированными.
- Предпочитайте понятные имена вместо "хитрых".
## Проверки
Перед PR запускайте:
```bash
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo check
```
## CI/CD и релизы
- CI: `.github/workflows/ci.yml`
- Release: `.github/workflows/release.yml`
- Релиз запускается по тегу `v*` и публикует бинарники для:
- `x86_64-unknown-linux-gnu`
- `x86_64-apple-darwin`
- `aarch64-apple-darwin`
- `x86_64-pc-windows-msvc`
## Коммиты и PR
- Делайте коммиты понятными.
- В PR указывайте краткое описание и мотивацию изменений.
- Обновляйте документацию при изменении поведения.
## Вопросы
Если что-то непонятно, открой issue или задайте вопрос в PR.
Также можно задать вопрос напрямую:
- TG: @dexoron
- DS: dexoron

102
docs-old/ru/FAQ_ru.md
View File

@@ -1,102 +0,0 @@
# FAQ
## В чем суть проекта?
`dcr` - это инструмент для управления C/C++ проектами и их зависимостями.
Он вдохновлен Cargo, но не является аналогом Makefile, CMake или других классических систем сборки.
Цель проекта - дать более простую и удобную в настройке среду для разработки.
## Как разрабатывается проект?
Проект написан на Rust и в основном развивается одним разработчиком - Dexoron.
В работе используются ИИ-инструменты, но они не пишут проект целиком: их роль - помощь с отдельными задачами (например, советы, проверка формулировок, переводы и т.д.).
## Какие инструменты используются для разработки?
Основной стек разработки:
- `RustRover` 2025 - IDE для разработки.
- `Codex` (`GPT-5.3-Codex (medium)`) - основной ИИ-инструмент, интегрированный через JetBrains AI Chat.
- `Rust` - основной язык проекта.
- `Cargo` - инструмент сборки, тестов и управления зависимостями Rust-проектов.
## Проект открытый?
Да, проект открыт (Open Source).
Вы можете предлагать идеи, находить ошибки и вносить изменения в код.
Проект распространяется по лицензии MIT (см. `LICENSE`).
## Как внести вклад?
Спасибо за желание помочь проекту.
Вы можете:
- помочь с кодом;
- помочь с переводом;
- помочь с документацией;
- предложить идею или сообщить о баге.
### Если вы хотите внести изменения (код, перевод, документация)
1. Сделайте форк нужного репозитория: `dexoron/dcr` (основной проект) или `dexoron/dcr-site` (сайт проекта).
2. Внесите изменения с учетом правил из `CONTRIBUTING.md`.
3. Отправьте изменения в свой форк.
4. Создайте Pull Request.
5. Дождитесь ревью.
### Если вы хотите сообщить о проблеме или предложить идею
1. Откройте нужный репозиторий: `dexoron/dcr` или `dexoron/dcr-site`.
2. Перейдите во вкладку `Issues`.
3. Создайте Issue и укажите тип (баг, предложение, вопрос/помощь).
4. Опишите проблему или идею кратко и понятно.
5. Дождитесь обратной связи.
## Как установить `dcr`?
Актуальные способы установки зависят от текущей версии проекта.
Рекомендуемый путь:
- проверьте инструкции в `README.md`;
- если готового пакета для вашей платформы нет, соберите проект из исходников через `cargo build --release`.
## Как быстро начать работу?
Минимальный сценарий:
1. Установите `dcr`.
2. Создайте проект (или перейдите в существующий C/C++ проект).
3. Инициализируйте конфигурацию `dcr`.
4. Добавьте зависимости проекта.
5. Запустите сборку через `dcr`.
Подробные команды и примеры смотрите в `README.md` и документации проекта.
## На какой стадии проект?
`dcr` активно развивается.
Это означает, что интерфейсы и поведение некоторых функций могут меняться между версиями.
Перед обновлением рекомендуется читать changelog и проверять заметки к релизу.
## С какими системами работает `dcr`?
`dcr` ориентирован на современные среды разработки C/C++.
Фактическая совместимость зависит от версии `dcr`, операционной системы и используемого toolchain.
Перед началом работы проверьте в документации:
- поддерживаемые ОС;
- поддерживаемые компиляторы и линкеры;
- ограничения конкретной версии.
## Чем `dcr` отличается от Make/CMake?
`dcr` не пытается быть прямой заменой Make/CMake.
Главный фокус `dcr` - упростить управление проектом и зависимостями в стиле, близком к опыту Cargo.
Если вам нужен низкоуровневый полный контроль над процессом сборки, классические инструменты могут быть привычнее.
Если нужна более простая и единообразная модель конфигурации - `dcr` может быть удобнее.
## Где смотреть документацию и примеры?
Основные источники:
- `README.md` в репозитории;
- документация проекта (смотреть сайт проекта);
- `Issues` для известных проблем и обсуждений;
## Как правильно сообщить о баге?
Чтобы баг-репорт можно было быстро воспроизвести, укажите:
1. Версию `dcr`.
2. ОС и версию компилятора/toolchain.
3. Шаги воспроизведения.
4. Ожидаемое поведение.
5. Фактическое поведение и текст ошибки.
6. Минимальный пример проекта (по возможности).
Баги и проблемы отправляйте через `Issues` в соответствующем репозитории.

158
docs-old/ru/README_ru.md
View File

@@ -1,158 +0,0 @@
# DCR (Dexoron Cargo Realization)
DCR — это утилита для управления проектами на C/C++ в стиле Cargo.
Текущая реализация написана на Rust.
## Зачем DCR
- Единая структура проекта без ручной настройки
- Простые команды для типовых задач
- Прозрачная компиляция и предсказуемые профили сборки
## Возможности
- Создание нового проекта или инициализация текущей директории
- Сборка проекта в профилях `debug` и `release`
- Запуск собранного бинарника
- Очистка результатов сборки
- Генерация минимального шаблона C-проекта
- Обновление бинарника через `dcr --update` (GitHub Releases, не для pacman-установок)
## Поддерживаемые платформы
- Linux: `x86_64-unknown-linux-gnu`
- macOS Intel: `x86_64-apple-darwin`
- macOS Apple Silicon: `aarch64-apple-darwin`
- Windows: `x86_64-pc-windows-msvc`
## Установка
### Пакетный менеджер
**ArchLinux**
```sh
yay -S dcr # или paru и остальные менеджеры пакетов AUR
```
### Из исходников
```sh
git clone https://github.com/dexoron/dcr.git
cd dcr
cargo build --release
mkdir -p ~/.local/bin
ln -sf "$PWD/target/release/dcr" ~/.local/bin/dcr
```
### Через install.sh (Linux/macOS)
```sh
curl -fsSL https://dcr.dexoron.su/install.sh | bash
```
### Через install.ps1 (Windows)
```powershell
irm https://dcr.dexoron.su/install.ps1 | iex
```
Оба скрипта при запуске спрашивают:
- скачать готовый бинарник из GitHub Release
- или собрать проект из `git`
Релизные ассеты:
- `dcr-x86_64-unknown-linux-gnu`
- `dcr-x86_64-apple-darwin`
- `dcr-aarch64-apple-darwin`
- `dcr-x86_64-pc-windows-msvc.exe`
## Обновление
- Если DCR установлен из GitHub Releases, через `install.sh`, `install.ps1` или собран вручную:
- используйте `dcr --update`
- Если DCR установлен через `pacman/AUR`:
- обновляйте через пакетный менеджер: `paru/yay -Syu dcr` или `sudo pacman -Syu dcr`
- `dcr --update` определяет пакетную установку и подсказывает обновляться через пакетный менеджер
## Быстрый старт
Создать новый проект:
`dcr new hello`
Или инициализировать текущую директорию (директория должна быть пустой):
`dcr init`
Структура проекта:
```txt
hello/
- src/
- - main.c
- dcr.toml
```
Сборка и запуск проекта:
`dcr run` или `dcr run --release`
## Команды
### `dcr new <name>`
Создает проект в текущей директории с указанным именем.
### `dcr init`
Создает проект в текущей директории. Имя проекта будет равно имени директории. Директория должна быть пустой.
### `dcr build [profile]`
Собирает проект. Если профиль не указан, используется `--debug`.
### `dcr run [profile]`
Собирает проект и запускает бинарник. Если профиль не указан, используется `--debug`.
Запуск вручную:
`./target/<profile>/<name>`
### `dcr clean`
Удаляет папку `target` в корне проекта.
## Профили сборки
Поддерживаются два профиля:
- `--debug` (по умолчанию) — встроенные флаги для каждого компилятора
- `--release` — встроенные флаги для каждого компилятора
Кастомные флаги можно добавить через `build.cflags` и `build.ldflags` в `dcr.toml`.
Можно указать `build.target`, чтобы задать директорию выхода бинарника (без привязки к профилю).
Используйте `build.kind = "staticlib"`, чтобы собрать статическую библиотеку вместо бинарника.
`dcr run` работает только для `build.kind = "bin"` и завершится ошибкой для `staticlib`.
## Конфигурация
Основной файл проекта — `dcr.toml`.
Пример `dcr.toml`:
```toml
[package]
name = "hello"
version = "0.1.0"
[build]
language = "c"
standard = "c11"
compiler = "clang"
# Опциональные флаги
cflags = ["-Wall", "-Wextra"]
ldflags = ["-lm"]
[dependencies]
```
Поддерживаются path-зависимости. DCR резолвит их при сборке и создаёт `dcr.lock`.
Примечание по инкрементальной сборке: пересборка объектников идёт по изменениям `.c/.cpp`. Учет зависимостей заголовков пока не реализован.
## Требования
- Rust toolchain (`rustc`, `cargo`) - Для ручной сборки DCR
- C-компилятор (`clang`, `gcc` или 'cl'(msvc))
## Релизы
Релизы собираются автоматически через GitHub Actions (`.github/workflows/release.yml`) при пуше тега формата `v*`.
## Лицензия
См. файл `LICENSE`.

33
docs/README.md
View File

@@ -1,2 +1,35 @@
# Introduction # Introduction
DCR (Dexoron Cargo Realization) is a Cargo-style CLI for C/C++ projects.
Current DCR focuses on a simple, predictable workflow:
- create or initialize a project (`dcr new`, `dcr init`)
- build with `debug` or `release` profiles (`dcr build`)
- run binaries (`dcr run`)
- clean artifacts (`dcr clean`)
- update the installed binary (`dcr --update`)
## What is implemented in this version
- Project configuration in `dcr.toml` with `[package]`, `[build]`, `[dependencies]`.
- Recursive source discovery in `src/`:
- C: `*.c`
- C++: `*.cpp`, `*.cxx`, `*.cc`
- Compiler selection from `dcr.toml` (`clang`, `gcc`, `cl`, `clang-cl`, etc.).
- Two build kinds:
- `bin` (default)
- `staticlib`
- Optional custom output directory via `build.target`.
- Path dependencies with include/lib resolution and `dcr.lock` generation.
## Important behavior notes
- `dcr.toml` is required for `build`, `run`, and `clean`.
- `run` works only with `build.kind = "bin"`.
- Incremental rebuild currently tracks source file timestamps (not header dependency graphs).
- Object files are always created under `target/<profile>/obj/`.
## Repository
- <https://github.com/dexoron/dcr>

2
docs/SUMMARY.md
View File

@@ -20,7 +20,7 @@
## Commands ## Commands
* [Global options](commands/global-options.md) * [Global options](commands/global-options.md)
* [dcr init/new](commands/dcr-init-new.md) * [dcr init/new](commands/dcr-init-or-new.md)
* [dcr build](commands/dcr-build.md) * [dcr build](commands/dcr-build.md)
* [dcr run](commands/dcr-run.md) * [dcr run](commands/dcr-run.md)
* [dcr clean](commands/dcr-clean.md) * [dcr clean](commands/dcr-clean.md)

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

@@ -1,2 +1,42 @@
# dcr build # dcr build
Builds the project in `debug` or `release` profile.
## Usage
```sh
dcr build
dcr build --debug
dcr build --release
```
## 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 static library).
## Config values used
- `package.name`
- `build.compiler`
- `build.language`
- `build.standard`
- `build.kind`
- `build.target`
- `build.cflags`
- `build.ldflags`
## Source selection
- `language = "c"` -> `*.c`
- `language = "c++" | "cpp" | "cxx"` -> `*.cpp`, `*.cxx`, `*.cc`
## Notes
- The profile is selected from the first argument only.
- Unknown profile flags return an error.
- Incremental rebuild is based on source/object mtime comparison.

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

@@ -1,2 +1,23 @@
# dcr clean # dcr clean
Removes build artifacts in `target/`.
## Usage
```sh
dcr clean
dcr clean --debug
dcr clean --release
```
## Behavior
- Without arguments: removes entire `target/`.
- With profile: removes only `target/<profile>/`.
## Validation
- `dcr.toml` must exist.
- More than one argument is treated as error.
- Unknown profile is treated as error.
- If `target` or selected profile directory does not exist, command prints a warning.

2
docs/commands/dcr-init-new.md
View File

@@ -1,2 +0,0 @@
# dcr init/new

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

@@ -0,0 +1,43 @@
# 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.

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

@@ -1,2 +1,27 @@
# dcr run # dcr run
Builds the project and runs the resulting binary.
## Usage
```sh
dcr run
dcr run --debug
dcr run --release
```
## 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.
## Restrictions
- If `build.kind = "staticlib"`, `run` exits with error.
- The profile is selected from the first argument.
## 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.

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

@@ -1,2 +1,44 @@
# Global options # 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.

37
docs/configuration/build-profiles.md
View File

@@ -1,2 +1,39 @@
# Build profiles # Build profiles
DCR supports two profiles:
- `debug` (default)
- `release`
## How to select
```sh
dcr build --debug
dcr build --release
dcr run --release
dcr clean --debug
```
## Default profile flags
### GCC/Clang-like toolchains
- `debug`: `-O0 -g -Wall -Wextra -fno-omit-frame-pointer -DDEBUG`
- `release`: `-O3 -DNDEBUG -march=native`
### MSVC toolchain
- `debug`: `/Od /Zi /W4 /DDEBUG /Oy-`
- `release`: `/O2 /DNDEBUG`
## Artifacts
By default:
- `target/debug/<name>` (or `.exe` on Windows)
- `target/release/<name>` (or `.exe` on Windows)
Static library mode (`kind = "staticlib"`):
- Linux/macOS: `lib<name>.a`
- Windows: `<name>.lib`

29
docs/configuration/build-section.md
View File

@@ -1,2 +1,31 @@
# Build section # Build section
## Schema
```toml
[build]
language = "c"
standard = "c11"
compiler = "clang"
kind = "bin"
# optional:
# target = "./dist"
# cflags = ["-Wall"]
# ldflags = ["-lm"]
```
## Fields
- `language` (string, required): `c`, `c++`, `cpp`, or `cxx`.
- `standard` (string, required): language standard passed to compiler.
- `compiler` (string, required): compiler command (for example `clang`, `gcc`, `cl`).
- `kind` (string, required): `bin` or `staticlib`.
- `target` (string, optional): custom output directory for final artifact.
- `cflags` (string array, optional): extra compile flags.
- `ldflags` (string array, optional): extra link flags.
## Behavior notes
- Compiler backend is selected by compiler string (`gcc`, `clang`, `cl`, `clang-cl`).
- Empty or unknown compiler value falls back to clang-like build path.
- `run` is not allowed for `kind = "staticlib"`.

43
docs/configuration/dcr.toml-overview.md
View File

@@ -1,2 +1,45 @@
# dcr.toml overview # dcr.toml overview
`dcr.toml` is the main project file used by DCR.
## Minimal generated template
```toml
[package]
name = "hello"
version = "0.1.0"
[build]
language = "c"
standard = "c11"
compiler = "clang"
kind = "bin"
[dependencies]
```
`dcr new` and `dcr init` generate this structure automatically.
## Required sections
- `[package]`
- `[build]`
- `[dependencies]`
## Required keys
- `package.name`
- `package.version`
- `build.language`
- `build.standard`
- `build.compiler`
- `build.kind`
`build.kind` must be either `bin` or `staticlib`.
## Optional keys
- `build.target`
- `build.cflags`
- `build.ldflags`
- dependency fields (`include`, `lib`, `libs`, `system`)

28
docs/configuration/dependencies-section.md
View File

@@ -1,2 +1,30 @@
# Dependencies section # Dependencies section
DCR currently supports path dependencies.
## Example
```toml
[dependencies]
frecli = { path = "./lib/frecli", include = ["."], lib = ["."], libs = ["frecli"] }
```
## Supported fields per dependency
- `path` (string, required): absolute path or path relative to project root.
- `include` (string array, optional): include directories inside dependency.
- `lib` (string array, optional): library directories inside dependency.
- `libs` (string array, optional): library names for linker.
- `system` (bool, optional): currently `system = true` is rejected.
## Defaults
- If `include` is omitted, DCR tries `<dep>/include`.
- If `lib` is omitted, DCR tries `<dep>/lib`, then `<dep>/lib64`.
- If `libs` is omitted, dependency key name is used.
## Validation
- Dependency value must be a TOML table.
- `path` is mandatory.
- `include`/`lib`/`libs` must be arrays of strings if provided.

18
docs/configuration/package-section.md
View File

@@ -1,2 +1,20 @@
# Package section # Package section
## Schema
```toml
[package]
name = "my-app"
version = "0.1.0"
```
## Fields
- `name` (string, required): used as output artifact base name.
- `version` (string, required): used in `dcr.lock` project entry.
## Notes
- Empty `name` or `version` makes config invalid.
- `dcr new` sets `name` from the passed project name.
- `dcr init` sets `name` from current directory name.

28
docs/dependencies-and-build/compilers-and-linking.md
View File

@@ -1,2 +1,30 @@
# Compilers & linking # Compilers & linking
## Compiler backend selection
DCR picks a backend from `build.compiler`:
- contains `clang-cl` -> MSVC backend
- contains `gcc` or `g++` -> GCC backend
- contains `clang` or `clang++` -> Clang backend
- equals `cl` or contains `msvc` -> MSVC backend
- otherwise -> Clang backend fallback
## Compilation model
- Source files are found recursively in `src/` based on `build.language`.
- Each source is compiled to `target/<profile>/obj/<relative-path>.o` (`.obj` on MSVC).
- Recompile happens when source mtime is newer than object mtime.
## Linking
For `kind = "bin"`:
- Object files are linked into executable artifact.
- Dependency lib dirs and library names are passed to linker.
- `build.ldflags` are appended to link command.
For `kind = "staticlib"`:
- Linux/macOS (GCC/Clang): `ar rcs` creates `.a` archive.
- Windows (MSVC): `lib` creates `.lib` archive.

24
docs/dependencies-and-build/dependency-format.md
View File

@@ -1,2 +1,26 @@
# Dependency format # Dependency format
Dependencies are defined in `dcr.toml` under `[dependencies]`.
## Full example
```toml
[dependencies]
fmt = { path = "./third_party/fmt", include = ["include"], lib = ["lib"], libs = ["fmt"] }
```
## Field reference
- `path`: required dependency root path.
- `include`: optional include subpaths (absolute or relative to dep root).
- `lib`: optional library subpaths (absolute or relative to dep root).
- `libs`: optional linker library names.
## Common valid compact form
```toml
[dependencies]
mylib = { path = "./libs/mylib" }
```
In this form DCR will try defaults for include/lib dirs and use `mylib` as the linker library name.

17
docs/dependencies-and-build/local-dependencies.md
View File

@@ -1,2 +1,19 @@
# Local dependencies # Local dependencies
## Resolution flow during build
For each dependency in `[dependencies]`, DCR:
1. Resolves `path` (absolute or project-relative).
2. Resolves include dirs (`include` or default `include`).
3. Resolves lib dirs (`lib` or defaults `lib`, `lib64`).
4. Resolves link libs (`libs` or dependency name).
5. Synchronizes dependency files to `target/<profile>/deps/<dep-name>/`.
6. Adds include/lib/link options to compile/link commands.
## Failure cases
- Dependency path is missing or not a directory.
- No valid include/lib directories were found.
- Any configured include/lib path does not exist.
- Invalid field types in dependency config.

21
docs/dependencies-and-build/target-directory.md
View File

@@ -1,2 +1,23 @@
# Target directory # Target directory
By default, DCR writes final artifacts to `target/<profile>/`.
You can override this with `build.target`:
```toml
[build]
target = "./dist"
```
## Behavior
- Binary mode:
- Linux/macOS: `<target>/<name>`
- Windows: `<target>/<name>.exe`
- Static library mode:
- Linux/macOS: `<target>/lib<name>.a`
- Windows: `<target>/<name>.lib`
## Important detail
`build.target` changes only the final artifact location. Object cache and dependency sync directories still use `target/<profile>/...`.

30
docs/dependencies-and-build/versioning-and-lock-file.md
View File

@@ -1,2 +1,32 @@
# Versioning & lock file # Versioning & lock file
DCR generates `dcr.lock` when dependency resolution succeeds and at least one dependency exists.
## What is stored
- Project entry (`name`, `version`, dependency names).
- One entry per resolved dependency:
- `name`
- `version` (from dependency `dcr.toml`, fallback `0.0.0`)
- `source` (`path+...`)
- `checksum` (SHA-256 over dependency files, excluding nested `target/`).
## Example shape
```toml
[[package]]
name = "my-app"
version = "0.1.0"
dependencies = ["fmt"]
[[package]]
name = "fmt"
version = "1.2.3"
source = "path+./third_party/fmt"
checksum = "..."
```
## Notes
- `dcr.lock` is rewritten on successful dependency resolution.
- If `[dependencies]` is empty, lock generation is skipped.

44
docs/getting-started/build-and-run.md
View File

@@ -1,2 +1,46 @@
# Build and run # Build and run
## Build
Debug (default):
```sh
dcr build
# or
dcr build --debug
```
Release:
```sh
dcr build --release
```
## Run
```sh
dcr run
# or
dcr run --release
```
`dcr run` first builds, then launches the produced binary.
## Clean artifacts
```sh
dcr clean
```
Profile-only cleanup:
```sh
dcr clean --debug
dcr clean --release
```
## Notes
- `run` is unavailable for `build.kind = "staticlib"`.
- Build profile flag is parsed from the first command argument.
- Unknown profile flags produce an error.

39
docs/getting-started/create-your-first-project.md
View File

@@ -1,2 +1,41 @@
# Create your first project # Create your first project
## Create in a new folder
```sh
dcr new hello
cd hello
```
This creates:
```text
hello/
- dcr.toml
- src/
- - main.c
```
## Or initialize current folder
```sh
mkdir hello
cd hello
dcr init
```
`dcr init` requires the current directory to be empty.
## Next steps
Build and run:
```sh
dcr run
```
Release build/run:
```sh
dcr run --release
```

54
docs/getting-started/installation.md
View File

@@ -1,2 +1,56 @@
# Installation # Installation
## Option 1: Install via script
### Linux/macOS
```sh
curl -fsSL https://dcr.dexoron.su/install.sh | bash
```
Alternative with `wget`:
```sh
wget -qO- https://dcr.dexoron.su/install.sh | bash
```
### Windows (PowerShell)
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://dcr.dexoron.su/install.ps1 | iex"
```
## Option 2: Build from source
```sh
git clone https://github.com/dexoron/dcr.git
cd dcr
cargo build --release
mkdir -p ~/.local/bin
ln -sf "$PWD/target/release/dcr" ~/.local/bin/dcr
```
## Option 3: Arch Linux (AUR)
```sh
yay -S dcr
```
(You can also use `paru` or other AUR helpers.)
## Verify installation
```sh
dcr --version
```
Expected format:
```text
dcr <version> (<target>)
```
## Update policy
- If DCR was installed from GitHub releases, scripts, or manual build: use `dcr --update`.
- If DCR is managed by `pacman/AUR`: update via package manager. On Linux, `dcr --update` detects pacman-owned binaries and prints a package-manager hint.

37
docs/getting-started/project-structure.md
View File

@@ -1,2 +1,39 @@
# Project structure # Project structure
## Minimal project
```text
project/
- dcr.toml
- src/
- - main.c
```
## Typical generated/optional files
```text
project/
- dcr.toml
- dcr.lock
- src/
- - ... source files ...
- target/
- - debug/
- - - obj/
- - - deps/
- - release/
- - - obj/
- - - deps/
```
## Meaning
- `dcr.toml`: main project configuration.
- `dcr.lock`: generated lock file for resolved path dependencies.
- `src/`: recursively scanned source directory.
- `target/<profile>/obj/`: cached object files for incremental rebuild.
- `target/<profile>/deps/`: synchronized copies of path dependencies.
- `target/<profile>/<name>` (or `.exe` on Windows): output for `kind = "bin"`.
- `target/<profile>/lib<name>.a` (or `<name>.lib` on Windows): output for `kind = "staticlib"`.
If `build.target` is set, the final artifact is written to that custom directory, while object cache still stays in `target/<profile>/obj`.

24
docs/reference-and-help/cli-reference.md
View File

@@ -1,2 +1,26 @@
# CLI reference # CLI reference
## Command list
```text
dcr new <name>
dcr init
dcr build [--debug|--release]
dcr run [--debug|--release]
dcr clean [--debug|--release]
dcr --help
dcr --version
dcr --update
```
## Notes on argument parsing
- Most commands parse profile from the first argument.
- `new` requires exactly one argument.
- `init` and `--update` do not accept extra arguments.
- `clean` accepts at most one argument.
## Exit behavior overview
- Successful command execution returns `0`.
- Validation/build/runtime errors return non-zero status.

39
docs/reference-and-help/config-reference.md
View File

@@ -1,2 +1,41 @@
# Config reference # Config reference
## Full schema
```toml
[package]
name = "string" # required
version = "string" # required
[build]
language = "c|c++|cpp|cxx" # required
standard = "string" # required
compiler = "string" # required
kind = "bin|staticlib" # required
target = "string" # optional
cflags = ["string", "..."] # optional
ldflags = ["string", "..."] # optional
[dependencies]
name = {
path = "string", # required for each dependency
include = ["string", "..."], # optional
lib = ["string", "..."], # optional
libs = ["string", "..."], # optional
}
```
## Validation rules
- `[package]`, `[build]`, `[dependencies]` must exist.
- Required string fields must be non-empty.
- `build.kind` must be `bin` or `staticlib`.
- Dependency fields `include/lib/libs` must be string arrays when provided.
## Generated defaults (`dcr new` / `dcr init`)
- `package.version = "0.1.0"`
- `build.language = "c"`
- `build.standard = "c11"`
- `build.compiler = "clang"`
- `build.kind = "bin"`

32
docs/reference-and-help/contributing-and-bug-reports.md
View File

@@ -1,2 +1,34 @@
# Contributing & Bug reports # Contributing & Bug reports
## Contribution workflow
1. Fork `dexoron/dcr` (and `dexoron/dcr-site` if docs website changes are needed).
2. Make focused changes.
3. Run checks locally:
```bash
cargo fmt --all
cargo clippy --all-targets --all-features -- -D warnings
cargo check
```
4. Open a PR with short rationale and behavior impact.
5. Update docs when CLI behavior changes.
## Bug report checklist
Include:
1. DCR version (`dcr --version`).
2. OS and compiler/toolchain version.
3. Reproduction steps.
4. Expected result.
5. Actual result and full error output.
6. Minimal reproducible project.
## Where to report
Use GitHub Issues in the relevant repository:
- <https://github.com/dexoron/dcr>
- <https://github.com/dexoron/dcr-site>

32
docs/reference-and-help/faq.md
View File

@@ -1,2 +1,34 @@
# FAQ # FAQ
## What commands are available?
`new`, `init`, `build`, `run`, `clean`, `--help`, `--version`, `--update`.
## Is `dcr.toml` mandatory?
Yes, for `build`, `run`, and `clean`.
## What source files are compiled?
DCR scans `src/` recursively:
- for C: `*.c`
- for C++: `*.cpp`, `*.cxx`, `*.cc`
## Can I switch compiler?
Yes. Set `build.compiler` in `dcr.toml` (for example `gcc`, `clang`, `cl`, `clang-cl`).
## How does incremental rebuild work?
It compares source file mtime with object file mtime. Header dependency tracking is not implemented yet.
## What does `dcr run` do if build fails?
It tries to run an existing binary from the selected profile; if none exists, it reports an error.
## How do I update DCR?
Use `dcr --update` for non-package-managed installs.
If installed through pacman/AUR, update via package manager.