91 lines
3.0 KiB
Markdown
91 lines
3.0 KiB
Markdown
|
# Development
|
||
|
|
|
||
|
|
How to work on nfs.
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- Go 1.27.1, the newest stable release.
|
||
|
|
- [just](https://github.com/casey/just) for the recipes.
|
||
|
|
- gcc, for the race detector in `just gates`.
|
||
|
|
|
||
|
|
## Setup
|
||
|
|
|
||
|
|
```sh
|
||
|
|
git clone https://sourcedock.dev/petrbalvin/nfs.git
|
||
|
|
cd nfs
|
||
|
|
just build
|
||
|
|
```
|
||
|
|
|
||
|
|
## Recipes
|
||
|
|
|
||
|
|
Every recipe in the project's file, and what it does. Taken from the file itself, so
|
||
|
|
the names and the list match it exactly.
|
||
|
|
|
||
|
|
| Recipe | What it does |
|
||
|
|
|---|---|
|
||
|
|
| `just gates` | the definition of done: build, format check, vet, modernisation, the test suite with the coverage floor, and the race detector |
|
||
|
|
| `just build` | compiles `cmd/nfsd` and `cmd/nfs` into `bin/nfsd` and `bin/nfs`, zero errors and zero warnings |
|
||
|
|
| `just test` | the full suite with no test cache and the 80 percent coverage floor |
|
||
|
|
| `just race` | the same suite under the race detector |
|
||
|
|
| `just unit ./internal/xdr 'TestName'` | a fast scoped run for iterating |
|
||
|
|
| `just fuzz FuzzXdr ./internal/xdr 60s` | a time boxed fuzz of one target in one package |
|
||
|
|
| `just bench` | the benchmarks, five counts, allocation stats on |
|
||
|
|
| `just fmt` | gofmt over the tree, in place |
|
||
|
|
| `just fmt-check` | zero diff, prints nothing when everything is formatted |
|
||
|
|
| `just vet` | `go vet` and `go fix -diff` |
|
||
|
|
| `just clean` | removes `bin/` and `coverage.out` |
|
||
|
|
| `just install` | builds, then copies `bin/nfsd` and `bin/nfs` into the user's bin directory |
|
||
|
|
| `just uninstall` | removes the installed binary |
|
||
|
|
| `just run` | runs the program in place; nfsd exits at once until it is given an export, so a real run passes flags to the built binary: `./bin/nfsd -export DIR` |
|
||
|
|
| `just dev` | the same as `run`, for now |
|
||
|
|
|
||
|
|
The test and bench recipes sweep `./internal/...`, and not
|
||
|
|
the whole tree: the thin `cmd/nfsd` and `cmd/nfs` count as zero coverage and
|
||
|
|
would drag the floor below 80 percent on their own. The protocol logic lives
|
||
|
|
under `internal/`.
|
||
|
|
|
||
|
|
## Running a single test
|
||
|
|
|
||
|
|
```sh
|
||
|
|
go test -run TestName ./package
|
||
|
|
```
|
||
|
|
|
||
|
|
Add `-v` for the sub-test names, and `-race` when the change touches concurrency.
|
||
|
|
`-count=1` defeats the test cache when a result looks stale.
|
||
|
|
|
||
|
|
## Coverage
|
||
|
|
|
||
|
|
```sh
|
||
|
|
just test
|
||
|
|
go tool cover -func=coverage.out
|
||
|
|
```
|
||
|
|
|
||
|
|
The `total:` line is the number that matters, and it stays at 80 percent or more.
|
||
|
|
|
||
|
|
## Benchmarks
|
||
|
|
|
||
|
|
```sh
|
||
|
|
just bench
|
||
|
|
```
|
||
|
|
|
||
|
|
Benchmark on an idle machine, and compare only runs made in one process against each other.
|
||
|
|
|
||
|
|
## Debugging the build
|
||
|
|
|
||
|
|
```sh
|
||
|
|
go build -gcflags='-m' ./... # inlining decisions
|
||
|
|
go build -gcflags='-S' ./... # what the compiler generated
|
||
|
|
```
|
||
|
|
|
||
|
|
## Continuous integration
|
||
|
|
|
||
|
|
Workflows live in `.gitea/workflows/` and run on the project's own runners. They are
|
||
|
|
written by hand rather than through `just`, but they enforce the same set of gates, so a
|
||
|
|
green `just gates` locally is the fastest way to a green pipeline.
|
||
|
|
|
||
|
|
## Releases
|
||
|
|
|
||
|
|
Releases are cut by merging `development` into `main` and tagging `vX.Y.Z`. The tag
|
||
|
|
drives the release workflow, which builds the assets and publishes the notes it
|
||
|
|
extracted from `CHANGELOG.md`.
|