This commit is contained in:
ari committed 2026-10-21 00:12:33 -04:00
1 parent d8ad1c44c5
commit 72fccc34f8
14 files changed
+811 -261

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# 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.