New docs

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/<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.

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.

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/<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.

docs/dependencies-and-build/target-directory.md

@@ -1,2 +1,23 @@
 # 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>/...`.

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.