4.1 KiB
Development
Building, testing and changing slinuxm. Design and internals are in ARCHITECTURE.md; open work is in TODO.md.
Toolchain
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:
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.
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.
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 isdetached. The sha gets-dirtywhen tracked files have uncommitted changes. Without git, missing parts areunknown. SLINUXM_GIT_SHA,SLINUXM_GIT_BRANCHandSLINUXM_BUILD_DATEoverride the parts;SLINUXM_VERSIONreplaces the whole string.SOURCE_DATE_EPOCHis ignored (Nix dev shells set it to 1980).nix builduses the commit date and short rev, with the branch fixed tonix. Override withpkgs.callPackage ./nix/package.nix { gitBranch = "main"; … }.Cargo.tomlkeeps a semver version, used asinfo.versionin the OpenAPI document so it does not change on every commit.
OpenAPI document
docs/openapi.json is generated from the code. Regenerate it after changing a route, an MCP tool, a response type or the crate version:
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; 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 opensslmust be empty). - Keep
config.example.toml, configuration.md and the NixOS module in step when adding config. - Keep
systemd/skyg-linux-tracker.serviceand the module'sserviceConfigin step.