69 lines
4.1 KiB
Markdown
69 lines
4.1 KiB
Markdown
# Development
|
|
|
|
Building, testing and changing `slinuxm`. Design and internals are in [ARCHITECTURE.md](../ARCHITECTURE.md); open work is in [TODO.md](../TODO.md).
|
|
|
|
## Toolchain
|
|
|
|
```sh
|
|
devenv shell # Rust, pkg-config, lld, libsystemd, nushell, otelcol-contrib; installs the git hooks
|
|
cargo build --release # target/release/slinuxm
|
|
```
|
|
|
|
Without devenv you need a Rust toolchain, `pkg-config`, the `lld` linker (`.cargo/config.toml` links with it) and the libsystemd development files.
|
|
|
|
`examples/` holds three small programs (`systemd_dump`, `journal_tail`, `docker_ps`) that run one source against the live host: `cargo run --example journal_tail`.
|
|
|
|
## Tests
|
|
|
|
All checks go through one runner, `dev/dev-test.nu`:
|
|
|
|
```sh
|
|
devenv shell -- dev-test lint # cargo fmt --check, clippy -D warnings, no openssl in the tree
|
|
devenv shell -- dev-test unit # cargo test --lib --bins
|
|
devenv shell -- dev-test integration [filter] [--nocapture] # cargo test --test '*'
|
|
devenv shell -- dev-test all # lint, unit, integration; stops at the first failure
|
|
devenv shell -- dev-test vm [vm|peers] # NixOS VM tests (slow, needs /dev/kvm)
|
|
devenv shell -- dev-test ci # all plus the VM test
|
|
devenv shell -- smoke # the real binary end to end
|
|
```
|
|
|
|
`devenv shell -- dev-test --help` shows the cargo or nix command behind each.
|
|
|
|
- Unit and integration tests use in-memory fakes for systemd, the journal and Docker, so they need no root, no Docker and no network.
|
|
- The smoke test builds and runs the real binary against a throwaway database: creates a token, serves on a free port, exercises `/healthz`, REST and MCP with and without the token, revokes it and checks a clean SIGTERM exit. Checks that need host data are skipped with a reason when the source is unavailable.
|
|
|
|
Shell completion for `dev-test`: Nushell `use dev/dev-test.nu *`; zsh `source <(nu dev/dev-test.nu completions zsh)` after `compinit`; an interactive `devenv shell` sets up bash. More in [consolidator.md](consolidator.md#testing).
|
|
|
|
## Git hooks
|
|
|
|
Entering `devenv shell` installs hooks that run formatting, clippy, linters and a secret scan on commit, and path-selected tests on push. Details: [hooks.md](hooks.md).
|
|
|
|
## Version stamp
|
|
|
|
The binary reports `YYYY.MM.DD-<branch>-<sha>`, for example `2026.10.21-main-435a54a`, in `--version`, `/healthz`, `/api/v1/ping`, MCP server info and the OTel `service.version`.
|
|
|
|
- The date is the build day (UTC). Characters outside `[A-Za-z0-9._-]` in the branch become `-`; a detached HEAD is `detached`. The sha gets `-dirty` when tracked files have uncommitted changes. Without git, missing parts are `unknown`.
|
|
- `SLINUXM_GIT_SHA`, `SLINUXM_GIT_BRANCH` and `SLINUXM_BUILD_DATE` override the parts; `SLINUXM_VERSION` replaces the whole string. `SOURCE_DATE_EPOCH` is ignored (Nix dev shells set it to 1980).
|
|
- `nix build` uses the commit date and short rev, with the branch fixed to `nix`. Override with `pkgs.callPackage ./nix/package.nix { gitBranch = "main"; … }`.
|
|
- `Cargo.toml` keeps a semver version, used as `info.version` in the OpenAPI document so it does not change on every commit.
|
|
|
|
## OpenAPI document
|
|
|
|
[`docs/openapi.json`](openapi.json) is generated from the code. Regenerate it after changing a route, an MCP tool, a response type or the crate version:
|
|
|
|
```sh
|
|
cargo run -- openapi --peers > docs/openapi.json
|
|
```
|
|
|
|
`tests/openapi.rs` fails when it is stale.
|
|
|
|
## Rules that matter when changing code
|
|
|
|
The full list is in [AGENTS.md](../AGENTS.md); the ones that bite:
|
|
|
|
- Read-only against the host. No code path may change a unit, a container or a file outside the state directory.
|
|
- `src/sources/` is the only code that talks to D-Bus, journald or Docker. REST, MCP and OTel call into it.
|
|
- No openssl anywhere in the dependency tree (`cargo tree -i openssl` must be empty).
|
|
- Keep `config.example.toml`, [configuration.md](configuration.md) and the NixOS module in step when adding config.
|
|
- Keep `systemd/skyg-linux-tracker.service` and the module's `serviceConfig` in step.
|