Developing Guide

Build lnk from source, test it, and ship a change to main. Where new code goes is in Architecture.

What you need

You need Rust and curl. Rustup installs the version the repository pins, from its rust-toolchain.toml, at your first cargo. The checks before a push also need shellcheck, and on Linux the sandbox's tests need bubblewrap and openssh-server.

Build and use it

cargo build selects the core by default and puts lnk in target/debug. Other Rust packages build when selected. To run an agent with the parts it needs from this checkout, follow Run a Development Agent.

cargo build
target/debug/lnk --help
target/debug/lnk module list
target/debug/lnk --link-registry

Install lnk puts lnk on your PATH, from source or a release.

Test

Tests run the workspace's programs from target/debug, so build them first. Local services and fakes need no paid account.

cargo test

cargo build --workspace --bins
cargo test --workspace

cargo test -p link-docs-check -p link-docs-check-code

Fast checks are the goal: every change waits on them. Measure expensive tests and preserve the behavior they prove when reducing their cost. A library builds doc tests only when its docs hold a Rust example: one with none sets doctest = false under [lib], and the first example added takes it out. The docs checks' doc-tests rule holds both.

Which packages build

The workspace's default members are the core. Select another package with -p <crate>, or every member with --workspace. Cargo resolves features for the selected packages. Expanding a selection can compile a shared dependency again with additional features. A core build never compiles a connection, harness adapter or the tools' document extractors.

Measure test execution

Use Test Timing to turn saved Cargo output into a module breakdown and a standalone chart. Keep the test command's status and machine settings with the report. Compilation and test execution are separate costs, and a failed or partial run is not a complete performance baseline.

Count the programs a command starts

Every program lnk or a module starts costs the user that program's start, so a command starts only what it needs. A test holds common commands to a budget, the most programs each may start in a fresh home: spawns.toml. It runs each under strace (a Linux tracer of system calls), counts every execve, and names each program started when a budget is exceeded. A machine without a working strace skips it through the testing kit's program gate.

cargo build --workspace --bins
cargo test -p link-cli spawns

Count one command by hand the same way, then read trace.txt for which programs started which.

strace -f -qq -e trace=execve -e signal=none -o trace.txt -- lnk agent list
grep -c '= 0$' trace.txt

A build from source also starts each module once with --link-describe to check its commit (Built from the same sources). A release build starts none of those, so it starts fewer than a budget allows.

A test's home, services and Keychain

A test that runs lnk gives it a temporary HOME and LNK_SERVICES=off. On a Mac, Link always keeps secrets in the Keychain, so the testing kit's child environment also points LNK_SECURITY at a stand-in for Apple's security tool (link_test_kit::keychain). A service's or a Keychain item's name doesn't depend on HOME, so without them a test on a Mac stops or replaces your agent and writes your Keychain.

The sandbox on Linux

The sandbox's tests need bubblewrap, as Gotchas says. On Linux with bubblewrap, the agent tests run the mini harness in the sandbox, with its endpoint served out by its proxy (bridge.rs).

Debug information

Every workspace owns one profile; CARGO_PROFILE_DEV_DEBUG=true enables debug info for a build, or cargo's --config 'profile.dev.package."<name>".debug=true' for one package.

Write a test

Unit tests live next to the code in each crate. A few rules keep tests working:

  • A test owns its environment inputs. Give a child process the values it needs with Command::env and remove optional ones with Command::env_remove. Do not assume a login shell has set USER, LOGNAME, HOME or an XDG variable. Test an optional value absent, empty and misleading when the behavior depends on it. Change a child's environment, never the test process's shared environment.
  • A test with a fake launcher uses a fixed username such as test-user. That account need not exist. Only tests exercising real OS identity look up the kernel's UID (geteuid for the effective user), resolving it through the account database or id -un when a name is required. USER and LOGNAME are optional, caller-controlled strings.
  • A test that runs lnk or a module gets them from link_test_kit::programs(), this workspace's target/debug (why), and one from another workspace from programs_in.
  • A first test in a module's main.rs needs the module's test = false removed from its Cargo.toml.
  • A test that runs cargo uses link_test_kit::cargo(), because any other way recompiles the workspace (why).
  • A test reaches its helpers through the testing kit, link-test-kit, a development dependency, and never writes one of its own: the kit's page lists each helper and the raw call it replaces.
  • A test's temporary folder is a link_test_kit::TempDir, removed when the test ends, failed or not (why).
  • On Linux, when killing a controller to check its child's lifetime, use an isolated subprocess as a subreaper and wait for the adopted child. Signal zero also succeeds for a zombie, so it cannot prove the child still runs. Keep process-wide subreaping out of concurrent tests. For asynchronous retirement, wait with a deadline for the actual cleanup; a published final record can precede it.
  • A test whose sandbox's proxy reaches a host by name gives the name an address with LNK_TEST_RESOLVE (example.com=192.0.2.1), so it passes on a machine without DNS, behind an HTTPS proxy alone (Claude Code on the web). The name never leaves the machine: the test's own upstream takes the connection.
  • A test whose sandbox's proxy speaks TLS to a host of its own (a fake git host) gives the proxy that host's certificate authority with LNK_TEST_CA (a PEM file), and reaches it through an upstream of its own (lnk sandbox run --upstream http://127.0.0.1:<port>, a CONNECT proxy), as sandbox's run::a_sealed_token_clones_with_git_and_stays_outside does.

Gotchas

Keep the checkout outside /tmp, which sandbox specifications cannot read. Use Development Environment for shared setup, build limits, credentials and the sandbox's platform requirements. A missing sandbox capability is reported explicitly; it does not establish sandbox coverage.

Background services and the Keychain

Tests that start background services or use the macOS Keychain give them isolated settings and disable user services. Use the shared test helpers to write programs, stop process groups and remove temporary directories. See Decisions for the helper contracts.

Before you push

Check a change with the docs and repository checks first, since they take seconds once built, then the packages you changed. Build the workspace's programs before their tests, since the tests run them:

cargo test -p link-docs-check -p link-docs-check-code -p link-repository-check
cargo fmt --all --check
cargo clippy --locked -p <package> --all-targets -- -D warnings
cargo build --locked --workspace --bins
cargo test --locked -p <package> --no-fail-fast

The full checks run the whole workspace, and all of them must pass before a change is merged. checks.yml runs them again on a push to main, before a release is published:

cargo fmt --all --check
cargo clippy --locked --workspace --all-targets -- -D warnings
cargo build --locked --workspace --bins
cargo test --locked --workspace --no-fail-fast

--no-fail-fast runs every test program even after one fails, as checks.yml does, so one failure never hides the others. Save the test command's output as Test Timings says, and its report sorts each failure as yours, the base's, a known flake or the machine's. Two checks they don't cover: the sandbox's unit tests on the release's libc, and shellcheck:

cargo test --locked --target x86_64-unknown-linux-musl -p link-sandbox -p link-sandbox-confine -p link-sandbox-proxy --lib
git ls-files '*.sh' | xargs shellcheck

checks.yml also runs the sandbox's unit tests on arm64 Linux, which has a release of its own. After a change to the sandbox, you can run them on x86_64 Linux under qemu-user. That needs sudo apt-get install qemu-user clang and rustup target add aarch64-unknown-linux-musl:

CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER=rust-lld \
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_RUNNER=qemu-aarch64 \
CC_aarch64_unknown_linux_musl=clang CFLAGS_aarch64_unknown_linux_musl=--target=aarch64-linux-musl \
  cargo test --locked --target aarch64-unknown-linux-musl -p link-sandbox -p link-sandbox-confine -p link-sandbox-proxy --lib

cargo test -p link-docs-check -p link-docs-check-code checks a change to the docs. The website's own checks, and translating the docs, are on The Website.

No warnings on a Mac

Code that runs on only one OS sits under its cfg, so a build for the other OS warns about whatever that leaves unused or unreachable. Clippy for a Mac (aarch64-apple-darwin) catches those and must pass too, and checks.yml runs it on a Mac.

Run it on Linux

Clippy compiles the Rust and links nothing, so it runs on Linux without a Mac's SDK (Software Development Kit, the Mac's system headers). It needs rustup target add aarch64-apple-darwin, clang and musl-tools. The C that dependencies build (ring, zstd and SQLite) is compiled against musl's headers as plain Unix code (-U__APPLE__) and never run:

CC_aarch64_apple_darwin=clang \
CFLAGS_aarch64_apple_darwin="--target=arm64-apple-macos11 -U__APPLE__ -nostdinc -isystem $(clang -print-resource-dir)/include -isystem /usr/include/x86_64-linux-musl" \
  cargo clippy --locked --workspace --all-targets --target aarch64-apple-darwin -- -D warnings

Fix a warning at its cause

A warning there is fixed with the cfg the code it names needs, an import moved under it, or the dead code deleted. Never allow(dead_code) or allow(unused).

Ship it

A change goes on a branch of its own off main, and into main by a pull request.

git checkout -b my-change origin/main

Try committed changes on a cloud machine with Developer Boxes. A release is a version bump merged into main, as Branches and Releases says.

More

The pages below hold the detail this one leaves out.