# 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--`, 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.