Skip to content

development.md

Latest commit

 

History

History
executable file
·
199 lines (147 loc) · 6.54 KB

development.md

File metadata and controls

executable file
·
199 lines (147 loc) · 6.54 KB
Raw

Development Guide

Environment setup, testing, and workflow for working on Intermesh.

Getting Started

Platform

  • Linux is required for Intermesh build and test workflows.
  • Use a Linux host directly (bare metal, VM, or cloud instance), or use Docker Desktop/Colima and run your workflow in a Linux container (mount the repo and the Docker socket).

Prompt-Driven Setup (especially useful on macOS/Windows)

If you are on macOS or Windows and want an assistant to drive setup, paste this into Claude Code (or similar).

Budget 10-20 minutes (sometimes a touch longer) for a first run. Most of that is unattended downloads and a cold Rust build. Several steps print nothing for minutes at a time; that is normal, not a hang.

I need a Linux-based Intermesh dev environment on this machine.
Create the smallest reliable setup and explain each step briefly.

Requirements:
- Intermesh tooling must run in Linux
- Docker daemon must be available
- Read this Intermesh development guide (where this prompt came from) first
  and treat it as the source of truth
- Repo is already cloned at <PATH_TO_INTERMESH> (ask user if no path was provided)
- Prefer manual tool install in Linux (rustup + protoc + cmake + ruby +
  pkg-config + musl-tools + git + build-essential)
- If using a container: mount the repo and the Docker socket, and set
  DOCKER_BUILDKIT=1 (the e2e image build requires BuildKit)
- If using a container: ensure docker CLI, buildx, and docker compose are
  installed in that container
- Set LANG=C.UTF-8 and LC_ALL=C.UTF-8 before running cargo local
- Nix is optional, not required

Please:
1) Detect host OS and choose a Linux execution path (native Linux, or Linux container/VM).
2) Give exact commands to set up dependencies.
3) Run verification commands and show pass/fail:
   - docker info
   - cargo --version
   - cargo local
4) Warn me before any step that takes more than a few minutes, and say how
   long it should take. The first cargo local runs 10-20 minutes and goes
   silent for long stretches; do not report it as hung or kill it.
5) If a step fails, show likely cause and next command to run.
6) End with a short checklist of what is done vs what is still needed.

Docker

Docker is required for e2e tests. Install it with your distro package manager on Linux, then confirm:

docker info

Setup

Option 1: Manual Setup (recommended)

If you want a straightforward, roll-your-own setup, install:

  • rustup (then run rustup toolchain install in this repo)
  • protoc
  • cmake
  • ruby
  • pkg-config
  • musl-tools
  • git
  • a C toolchain (build-essential on Debian/Ubuntu)
  • flock (usually provided by util-linux)

rust-toolchain.toml pins Rust, clippy, rustfmt, rust-analyzer, and targets.

Option 2: Nix + direnv

Nix gives a reproducible dev shell with the exact toolchain and versions:

If you'd rather not manage tool versions yourself, use this.

Verify Your Setup

Run the full local check:

cargo local

This runs formatting, lint, build, unit tests, and e2e tests.

Expect 10-20 minutes the first time. The cold Rust build and the e2e image build take most of the time, and both go quiet for minutes at a time. Later runs are much faster once the build cache and the e2e base image are warm.

Core Commands

  • cargo build - build the project
  • cargo test [filter] - run unit tests; pass a filter to run just the tests whose name matches it, e.g. cargo test my_test_name
  • cargo lint - run format check, clippy, and custom lints
  • cargo local - lint + build + unit tests + e2e tests
  • cargo all - local plus perf tests and VM tests when Incus is available
  • cargo deps - dependency freshness and vulnerability checks

E2E Tests

cargo test-e2e            # run all e2e tests
cargo test-e2e test_name  # run a specific test

E2E tests run Docker containers on a local bridge network with binaries built from your working tree.

If you run inside a dev container, install docker CLI + buildx + compose in that container so commands like cargo test-e2e and docker compose work.

VM Tests

VM tests run intermesh across isolated local Incus VMs. They run in CI, so most contributors never need a local Incus setup; reach for them when you want guest-level network realism before pushing.

You only need this if you plan to run VM tests locally. The Nix shell includes the incus CLI, but it does not install or configure the host Incus daemon. Your host should be able to launch the Ubuntu 24.04 cloud VM image:

incus image info images:ubuntu/24.04/cloud --vm
incus launch images:ubuntu/24.04/cloud intermesh-incus-check --vm --ephemeral
incus delete --force intermesh-incus-check

Quick commands:

cargo xtask vm-image         # ensure the cached VM image exists, print its alias
cargo test-vm                # run all VM tests; fails if Incus is unavailable
cargo test-vm test_name      # run a specific test
cargo xtask clean-vm-images  # drop cached local Intermesh VM images

cargo all attempts VM tests and skips them when Incus is unavailable.

Local Mesh Demo

The repo ships a small local mesh demo in sandbox/:

# first run takes time
cd sandbox && docker compose up -d

See sandbox/README.md for what to try once it's up and running.

Day-to-Day Workflow

A tight loop that works well:

  1. cargo test [filter]
  2. cargo lint
  3. cargo test-e2e [filter]
  4. cargo local before push

Common Gotchas

  • Docker daemon not reachable: start Docker and re-run docker info
  • Lint fails with invalid byte sequence in US-ASCII: set LANG=C.UTF-8 LC_ALL=C.UTF-8
  • First e2e run is slow: expected; the e2e base image and build cache have to warm up. Long silent stretches are normal, so let it finish
  • VM tests skipped: expected without a local Incus setup
  • Using a Linux dev container on macOS/Windows: set CARGO_TARGET_DIR to a container-local path to avoid host/guest target dir conflicts (for example export CARGO_TARGET_DIR=/tmp/intermesh-target)

Stuck on something platform-specific? File a GitHub issue: https://github.com/pcnofelt/intermesh/issues

Next Steps

  1. Get cargo local passing
  2. Run cargo test-e2e once to warm the environment
  3. Bring up the sandbox/ demo mesh
  4. Pick a small issue and follow the day-to-day loop above