diff --git a/docs-old/dcr-toml.md b/docs-old/dcr-toml.md deleted file mode 100644 index 1592abc..0000000 --- a/docs-old/dcr-toml.md +++ /dev/null @@ -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. diff --git a/docs-old/index.md b/docs-old/index.md deleted file mode 100644 index 4839e4e..0000000 --- a/docs-old/index.md +++ /dev/null @@ -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`). diff --git a/docs-old/ru/CONTRIBUTING_ru.md b/docs-old/ru/CONTRIBUTING_ru.md deleted file mode 100644 index 96a46df..0000000 --- a/docs-old/ru/CONTRIBUTING_ru.md +++ /dev/null @@ -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 diff --git a/docs-old/ru/FAQ_ru.md b/docs-old/ru/FAQ_ru.md deleted file mode 100644 index 87fd362..0000000 --- a/docs-old/ru/FAQ_ru.md +++ /dev/null @@ -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` в соответствующем репозитории. diff --git a/docs-old/ru/README_ru.md b/docs-old/ru/README_ru.md deleted file mode 100644 index 707b830..0000000 --- a/docs-old/ru/README_ru.md +++ /dev/null @@ -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 ` -Создает проект в текущей директории с указанным именем. - -### `dcr init` -Создает проект в текущей директории. Имя проекта будет равно имени директории. Директория должна быть пустой. - -### `dcr build [profile]` -Собирает проект. Если профиль не указан, используется `--debug`. - -### `dcr run [profile]` -Собирает проект и запускает бинарник. Если профиль не указан, используется `--debug`. - -Запуск вручную: -`./target//` - -### `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`. diff --git a/docs/README.md b/docs/README.md index 3d07efe..8e5b8d7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,2 +1,35 @@ # 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//obj/`. + +## Repository + +- diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 0a63414..5e0a23a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -20,7 +20,7 @@ ## Commands * [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 run](commands/dcr-run.md) * [dcr clean](commands/dcr-clean.md) diff --git a/docs/commands/dcr-build.md b/docs/commands/dcr-build.md index cfa35ad..fe2c852 100644 --- a/docs/commands/dcr-build.md +++ b/docs/commands/dcr-build.md @@ -1,2 +1,42 @@ # 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. diff --git a/docs/commands/dcr-clean.md b/docs/commands/dcr-clean.md index f9de051..2da92b8 100644 --- a/docs/commands/dcr-clean.md +++ b/docs/commands/dcr-clean.md @@ -1,2 +1,23 @@ # 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//`. + +## 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. diff --git a/docs/commands/dcr-init-new.md b/docs/commands/dcr-init-new.md deleted file mode 100644 index f8cd75b..0000000 --- a/docs/commands/dcr-init-new.md +++ /dev/null @@ -1,2 +0,0 @@ -# dcr init/new - diff --git a/docs/commands/dcr-init-or-new.md b/docs/commands/dcr-init-or-new.md new file mode 100644 index 0000000..905ca0d --- /dev/null +++ b/docs/commands/dcr-init-or-new.md @@ -0,0 +1,43 @@ +# dcr init/new + +## `dcr new ` + +Creates a new project directory and initializes it. + +```sh +dcr new hello +``` + +Behavior: + +1. Validates arguments (`` is required, only one name is allowed). +2. Creates `/`. +3. Creates `/dcr.toml`. +4. Sets `package.name = ""`. +5. Creates `/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. diff --git a/docs/commands/dcr-run.md b/docs/commands/dcr-run.md index ebf88e1..89ebfa8 100644 --- a/docs/commands/dcr-run.md +++ b/docs/commands/dcr-run.md @@ -1,2 +1,27 @@ # 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. diff --git a/docs/commands/global-options.md b/docs/commands/global-options.md index 297a781..a00144b 100644 --- a/docs/commands/global-options.md +++ b/docs/commands/global-options.md @@ -1,2 +1,44 @@ # Global options +## `dcr --help` + +```sh +dcr --help +``` + +Prints top-level CLI usage, commands, flags, and examples. + +## `dcr --version` + +```sh +dcr --version +``` + +Prints: + +```text +dcr () +``` + +## `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. diff --git a/docs/configuration/build-profiles.md b/docs/configuration/build-profiles.md index d2575d4..96eb107 100644 --- a/docs/configuration/build-profiles.md +++ b/docs/configuration/build-profiles.md @@ -1,2 +1,39 @@ # 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/` (or `.exe` on Windows) +- `target/release/` (or `.exe` on Windows) + +Static library mode (`kind = "staticlib"`): + +- Linux/macOS: `lib.a` +- Windows: `.lib` diff --git a/docs/configuration/build-section.md b/docs/configuration/build-section.md index 5496d4f..08e9617 100644 --- a/docs/configuration/build-section.md +++ b/docs/configuration/build-section.md @@ -1,2 +1,31 @@ # 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"`. diff --git a/docs/configuration/dcr.toml-overview.md b/docs/configuration/dcr.toml-overview.md index 6411dde..bafa7f8 100644 --- a/docs/configuration/dcr.toml-overview.md +++ b/docs/configuration/dcr.toml-overview.md @@ -1,2 +1,45 @@ # 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`) diff --git a/docs/configuration/dependencies-section.md b/docs/configuration/dependencies-section.md index 786ae7c..ba5bcaa 100644 --- a/docs/configuration/dependencies-section.md +++ b/docs/configuration/dependencies-section.md @@ -1,2 +1,30 @@ # 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 `/include`. +- If `lib` is omitted, DCR tries `/lib`, then `/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. diff --git a/docs/configuration/package-section.md b/docs/configuration/package-section.md index 291c0b6..1f0fcfe 100644 --- a/docs/configuration/package-section.md +++ b/docs/configuration/package-section.md @@ -1,2 +1,20 @@ # 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. diff --git a/docs/dependencies-and-build/compilers-and-linking.md b/docs/dependencies-and-build/compilers-and-linking.md index 994ce2f..592510a 100644 --- a/docs/dependencies-and-build/compilers-and-linking.md +++ b/docs/dependencies-and-build/compilers-and-linking.md @@ -1,2 +1,30 @@ # 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//obj/.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. diff --git a/docs/dependencies-and-build/dependency-format.md b/docs/dependencies-and-build/dependency-format.md index 53b20a9..8ba83b1 100644 --- a/docs/dependencies-and-build/dependency-format.md +++ b/docs/dependencies-and-build/dependency-format.md @@ -1,2 +1,26 @@ # 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. diff --git a/docs/dependencies-and-build/local-dependencies.md b/docs/dependencies-and-build/local-dependencies.md index dcef874..40dbb9a 100644 --- a/docs/dependencies-and-build/local-dependencies.md +++ b/docs/dependencies-and-build/local-dependencies.md @@ -1,2 +1,19 @@ # 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//deps//`. +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. diff --git a/docs/dependencies-and-build/target-directory.md b/docs/dependencies-and-build/target-directory.md index 92f8c58..c4d333e 100644 --- a/docs/dependencies-and-build/target-directory.md +++ b/docs/dependencies-and-build/target-directory.md @@ -1,2 +1,23 @@ # Target directory +By default, DCR writes final artifacts to `target//`. + +You can override this with `build.target`: + +```toml +[build] +target = "./dist" +``` + +## Behavior + +- Binary mode: + - Linux/macOS: `/` + - Windows: `/.exe` +- Static library mode: + - Linux/macOS: `/lib.a` + - Windows: `/.lib` + +## Important detail + +`build.target` changes only the final artifact location. Object cache and dependency sync directories still use `target//...`. diff --git a/docs/dependencies-and-build/versioning-and-lock-file.md b/docs/dependencies-and-build/versioning-and-lock-file.md index 1f61038..22ede17 100644 --- a/docs/dependencies-and-build/versioning-and-lock-file.md +++ b/docs/dependencies-and-build/versioning-and-lock-file.md @@ -1,2 +1,32 @@ # 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. diff --git a/docs/getting-started/build-and-run.md b/docs/getting-started/build-and-run.md index 789d4e6..bb4b6fa 100644 --- a/docs/getting-started/build-and-run.md +++ b/docs/getting-started/build-and-run.md @@ -1,2 +1,46 @@ # 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. diff --git a/docs/getting-started/create-your-first-project.md b/docs/getting-started/create-your-first-project.md index b05cd9a..a6bcf95 100644 --- a/docs/getting-started/create-your-first-project.md +++ b/docs/getting-started/create-your-first-project.md @@ -1,2 +1,41 @@ # 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 +``` diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 4026317..14e3e10 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,2 +1,56 @@ # 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 () +``` + +## 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. diff --git a/docs/getting-started/project-structure.md b/docs/getting-started/project-structure.md index 22f52ed..0550d99 100644 --- a/docs/getting-started/project-structure.md +++ b/docs/getting-started/project-structure.md @@ -1,2 +1,39 @@ # 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//obj/`: cached object files for incremental rebuild. +- `target//deps/`: synchronized copies of path dependencies. +- `target//` (or `.exe` on Windows): output for `kind = "bin"`. +- `target//lib.a` (or `.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//obj`. diff --git a/docs/reference-and-help/cli-reference.md b/docs/reference-and-help/cli-reference.md index f98f450..ed71afc 100644 --- a/docs/reference-and-help/cli-reference.md +++ b/docs/reference-and-help/cli-reference.md @@ -1,2 +1,26 @@ # CLI reference +## Command list + +```text +dcr new +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. diff --git a/docs/reference-and-help/config-reference.md b/docs/reference-and-help/config-reference.md index 20fa6ac..5458d77 100644 --- a/docs/reference-and-help/config-reference.md +++ b/docs/reference-and-help/config-reference.md @@ -1,2 +1,41 @@ # 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"` diff --git a/docs/reference-and-help/contributing-and-bug-reports.md b/docs/reference-and-help/contributing-and-bug-reports.md index d663264..74ef824 100644 --- a/docs/reference-and-help/contributing-and-bug-reports.md +++ b/docs/reference-and-help/contributing-and-bug-reports.md @@ -1,2 +1,34 @@ # 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: + +- +- diff --git a/docs/reference-and-help/faq.md b/docs/reference-and-help/faq.md index a39c1bc..e223667 100644 --- a/docs/reference-and-help/faq.md +++ b/docs/reference-and-help/faq.md @@ -1,2 +1,34 @@ # 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.