Files
2026-10-21 00:12:33 -04:00

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 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 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 openssl must be empty).
  • Keep config.example.toml, configuration.md and the NixOS module in step when adding config.
  • Keep systemd/skyg-linux-tracker.service and the module's serviceConfig in step.