mirror of
https://github.com/lima-vm/lima.git
synced 2026-10-28 11:44:35 +08:00
Akihiro Suda
c80fad98ad
gomodjail v2 moves the focus to static analysis: `gomodjail analyze` verifies that the modules annotated `gomodjail:confined` in go.mod cannot reach a denied capability (filesystem, network, process execution, raw syscalls, OS state modification, or cgo). Add gomodjail to ./hack/tools, add a `gomodjail` lint target, and wire it into `make lint` and the "Lints" job. Unlike the legacy dynamic mode, this gate is blocking. The verdicts are platform-dependent, so the gate is pinned to linux/amd64 and linux/arm64. These are the only platforms that can be analyzed from any host: analyzing darwin needs a macOS host, as the "vz" driver requires cgo. The linux verdicts are a superset of the darwin ones anyway. Windows is deliberately left out, as it would unconfine 18 more modules (go-yaml, containerd/log, go-runewidth, ...) and weaken the gate for the other platforms. `gomodjail fix` downgraded 36 modules to `gomodjail:unconfined` to make the gate pass. 65 modules remain confined: 37 clean, 28 warning-only. `make gomodjail-fix` is added for redoing this on dependency bumps, so that the decision stays visible and reviewable in go.mod. The macOS job that exercises the legacy dynamic mode (`gomodjail run`) is kept as an experiment, with its checkout pinned to v2.0.1 instead of HEAD. Assisted-by: Claude Code (Opus 5) Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
53 lines
2.6 KiB
Markdown
53 lines
2.6 KiB
Markdown
# AGENTS.md
|
|
|
|
Guidance for AI coding agents working in the Lima repository. It points to the authoritative docs
|
|
instead of duplicating them, so it stays in sync with the code.
|
|
|
|
## AI contribution rules
|
|
|
|
Read @website/content/en/docs/community/contributing.md and follow its "AI Contribution Rules"
|
|
section.
|
|
|
|
## Build, test, lint
|
|
|
|
Lima is `github.com/lima-vm/lima/v2` (imports use the `/v2` suffix). The build
|
|
uses a GNU Makefile; output goes to `_output/`.
|
|
|
|
```bash
|
|
make native # build limactl + native guestagent + templates (fastest full dev build)
|
|
make minimal # build just limactl + native guestagent + default template
|
|
go test ./... # unit tests - never boot VMs
|
|
make bats # integration tests (BATS); boot real VMs (needs git submodules)
|
|
make lint # editorconfig, golangci-lint, yamllint, ls-lint, shellcheck, ltag, ...
|
|
make generate # regenerate protobuf after editing a .proto file
|
|
```
|
|
|
|
Unit tests never execute VMs; anything that boots a VM is a BATS or template test under `hack/`
|
|
(for example `./hack/test-templates.sh ./templates/default.yaml`). Every commit must be signed off
|
|
with `git commit -s`, or CI fails.
|
|
|
|
## Where things are
|
|
|
|
Pointers to the authoritative sources - read these rather than a duplicated copy here.
|
|
|
|
- Architecture, the three processes (`limactl` / hostagent / guestagent), the on-disk `${LIMA_HOME}`
|
|
layout, and every `LIMA_CIDATA_*` variable:
|
|
[`website/content/en/docs/dev/internals.md`](website/content/en/docs/dev/internals.md).
|
|
- Config / data model: `pkg/limatype` (core `LimaYAML` / `Instance` types), `pkg/limayaml`
|
|
(load / default / validate), `pkg/limatmpl` and `pkg/templatestore` (templates).
|
|
- Drivers (virtualization backends): `pkg/driver/`
|
|
- Guest provisioning: `pkg/cidata/` builds `cidata.iso` (guestagent binary, boot scripts, and the
|
|
`user-data` file). `user-data` uses the cloud-config YAML format defined by cloud-init, which a
|
|
guest may consume with an implementation other than Python cloud-init.
|
|
- Instance lifecycle: `pkg/instance/`.
|
|
|
|
## Conventions
|
|
|
|
- New Go, shell, Dockerfile, and Makefile files need an SPDX header (`ltag` enforces this in CI;
|
|
other file types, including markdown, are exempt).
|
|
- Keep the `gomodjail` / `gosocialcheck` annotations in `go.mod`. `make gomodjail` statically
|
|
verifies that the modules annotated `gomodjail:confined` cannot reach a denied capability
|
|
(filesystem, network, process execution, raw syscalls, ...); when a dependency bump makes one
|
|
of them reach a capability, `make gomodjail-fix` downgrades that annotation to
|
|
`gomodjail:unconfined` instead of confining it by hand.
|