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 buildtarget/debug/lnk --helptarget/debug/lnk module listtarget/debug/lnk --link-registryInstall 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 --binscargo test --workspace
cargo test -p link-docs-check -p link-docs-check-codeFast 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 --binscargo test -p link-cli spawnsCount 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 listgrep -c '= 0$' trace.txtA 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::envand remove optional ones withCommand::env_remove. Do not assume a login shell has setUSER,LOGNAME,HOMEor 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 (geteuidfor the effective user), resolving it through the account database orid -unwhen a name is required.USERandLOGNAMEare optional, caller-controlled strings. - A test that runs
lnkor a module gets them fromlink_test_kit::programs(), this workspace'starget/debug(why), and one from another workspace fromprograms_in. - A first test in a module's
main.rsneeds the module'stest = falseremoved from itsCargo.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), assandbox'srun::a_sealed_token_clones_with_git_and_stays_outsidedoes.
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-checkcargo fmt --all --checkcargo clippy --locked -p <package> --all-targets -- -D warningscargo build --locked --workspace --binscargo test --locked -p <package> --no-fail-fastThe 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 --checkcargo clippy --locked --workspace --all-targets -- -D warningscargo build --locked --workspace --binscargo 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 --libgit ls-files '*.sh' | xargs shellcheckchecks.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 --libcargo 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 warningsFix 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/mainTry 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.
- Architecture: the core and its modules, and where new code goes
- Conventions: the rules every change follows
- Writing Docs: how a doc is written, where it goes, and its limits
- Development Environment: what a machine needs to build and test Link
- Testing Kit: the helpers every test uses, and what each replaces
- Test Environments: the rules that keep a test correct on every machine it runs on
- Skipping Tests: when a test skips, how, and every variable that decides it
- Test Troubleshooting: what a failing run says, and its cause and fix
- Write a Module: adding a module, harness, connection or cloud
- Module Contracts: what each
lnk ... --jsonprints - Specs and Command Lines: adding a command's flags, or a spec, and its tests
- Decisions: why it works this way