---
sidebar_label: Dependencies
---

# Dependencies

## Formats

The `[dependencies]` section supports registry, path, Git, and `pkg-config` dependencies:

### String (registry)

```toml
[dependencies]
fmt = "10.1.1"
spdlog = "1.12"
catch2 = "3.4.0"
```

The version string is used as-is for registry lookup.

### Table (git)

```toml
[dependencies]
dcr-math = { git = "https://github.com/dexoron/dcr-math-lib.git", tag = "v0.1.0" }
```

Fields: `git`, `branch`, `tag`, `rev`, `mode`, `include`, `lib`, `libs`.

### Table (path)

```toml
[dependencies]
mylib = { path = "../mylib" }
```

For a prebuilt external library, specify its layout explicitly. The three
arrays are paths relative to the dependency root (`include`, `lib`) and linker
names (`libs`):

```toml
[dependencies]
dcr-math = { path = "../deps/dcr-math", include = ["include"], lib = ["lib"], libs = ["dcr-math"] }
```

### Table (`pkg-config`)

Use an installed `.pc` package when the library is provided by the operating system
or another system package manager. DCR invokes `pkg-config --cflags` and
`pkg-config --libs`, preserving include, library, linker, and other flags:

```toml
[dependencies]
fmt = { pkg-config = "fmt" }
openssl = { pkg-config = ["openssl", "libcrypto"] }
```

The `pkg-config` executable must be available in `PATH`. The named `.pc` files must
be available through pkg-config's standard search paths or via `PKG_CONFIG_PATH`.
These dependencies are not downloaded or built by DCR; they are recorded in
`dcr.lock` with a `pkg-config+...` source.

## Registry

DCR uses a package registry for dependency lookup by name.

```toml
# ~/.dcr/config.toml
[registry.default]
url = "https://index.dcr.dexoron.tech"
priority = 1
```

Registry priority: order in `config.toml`. The `DCR_INDEX_PATH` variable overrides the path to `index.json`.

## Git dependencies

Git dependencies are cloned into `~/.dcr/git/`; their exact checked-out commit is written to `dcr.lock`.

Both Git and path dependencies have two modes:

- **DCR package:** the source has `dcr.toml`. DCR builds it before the consumer and uses the package name from its manifest for linking.
- **Prebuilt library:** it provides existing headers and binaries through `include`, `lib`, and `libs`. DCR passes them to the compiler/linker without building the dependency.

The mode is normally detected automatically. Use `mode = "build"` or `mode = "prebuild"` when a source contains both a manifest and prebuilt artifacts and you need to choose explicitly.

`dcr-math-lib` publishes both forms. Select its prebuilt library explicitly:

```toml
[dependencies]
dcr-math = { git = "https://github.com/dexoron/dcr-math-lib.git", tag = "v0.1.0", mode = "prebuild", include = ["include"], lib = ["lib"], libs = ["dcr-math"] }
```

DCR supports specifying branch/tag/rev for git sources:

- `branch` — switch to a branch
- `tag` — switch to a tag
- `rev` — switch to a specific commit
- `features` — feature flags (parsed, but does not affect build)

## Path dependencies

Local paths may point at a DCR package or a prebuilt external library. A path DCR package is built before its consumer, including its own path/git dependencies. DCR detects dependency cycles. A prebuilt library is never built by DCR; it is linked from the directories declared in its dependency entry.

```toml
[dependencies]
mylib = { path = "/abs/path/to/lib" }
mylib = { path = "../relative/path" }
```

For DCR packages, the package name from `dcr.toml` is used for linking (so the dependency key may differ from the library name). Header resolution includes the packaged `target/include` directory and link search includes `target/lib`.

### Recommended library layouts

Buildable DCR library:

```text
dcr-math-lib/
├── dcr.toml
└── src/
    ├── dcr_math.c
    └── dcr_math.h
```

Prebuilt library:

```text
dcr-math-lib/
├── include/
│   └── dcr_math.h
└── lib/
    └── libdcr-math.a       # or .so / .lib
```

`libs` contains linker names without the `lib` prefix and file extension: use
`["dcr-math"]` for `libdcr-math.a`.

If one repository contains both forms, keep the prebuilt files in `include/` and `lib/` and select the mode explicitly:

```toml
[dependencies]
dcr-math = { git = "https://github.com/dexoron/dcr-math-lib.git", tag = "v0.1.0", mode = "prebuild", include = ["include"], lib = ["lib"], libs = ["dcr-math"] }
```

For a local copy, replace `git` with `path = "../dcr-math-lib"`. In `prebuild` mode DCR does not run the dependency build, even when `dcr.toml` is present.

## dcr.lock

Dependency lock file. Contains package names and sources.

Created during `dcr build` for resolved registry, path, and Git dependencies. Not updated during `dcr add` — only on the next `dcr build`.

## Resolution process

1. Resolve dependency sources (registry → git → path)
2. Fetch git dependencies into `~/.dcr/git/` and check out the requested ref
3. Build DCR package dependencies recursively
4. Collect `include_dirs`, `lib_dirs`, `libs` for the compiler