102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
# Development
|
|
|
|
Requires Go (see `go.mod`). No CGO, no external tools.
|
|
|
|
```sh
|
|
make build # bin/mapsize, bin/treegen
|
|
make test # go test ./...
|
|
make race # go test -race ./...
|
|
make vet fmt-check
|
|
make benchmark # go test -bench
|
|
make fuzz # short fuzz runs of snapshot / treemap / filter
|
|
make release # release archives and packages in bin/release
|
|
```
|
|
|
|
## Releasing
|
|
|
|
Example for 1.2.0; substitute the real version throughout.
|
|
|
|
1. Update the version in `internal/brand/brand.go` and `docs/mapsize.1`,
|
|
and add a `## 1.2.0` section to CHANGELOG.md. Commit.
|
|
2. Tag and push:
|
|
```sh
|
|
git tag -a v1.2.0 -m "mapsize 1.2.0"
|
|
git push origin master v1.2.0
|
|
```
|
|
3. Build everything (archives, .deb/.rpm/.apk/Arch packages, SHA256SUMS
|
|
into `bin/release`; the first run downloads `nfpm`):
|
|
```sh
|
|
make release VERSION=v1.2.0
|
|
```
|
|
4. Publish the GitHub release with the changelog section as notes:
|
|
```sh
|
|
awk '/^## 1.2.0/{f=1;next} /^## /{f=0} f' CHANGELOG.md > /tmp/notes.md
|
|
gh release create v1.2.0 --title v1.2.0 --notes-file /tmp/notes.md bin/release/*
|
|
```
|
|
5. Update Homebrew. This needs the tag pushed (step 2), because it
|
|
checksums GitHub's source tarball for that tag:
|
|
```sh
|
|
make brew-formula VERSION=v1.2.0 # writes bin/homebrew/mapsize.rb
|
|
git clone https://github.com/andydixon/homebrew-tap /tmp/tap
|
|
cp bin/homebrew/mapsize.rb /tmp/tap/Formula/mapsize.rb
|
|
git -C /tmp/tap commit -am "mapsize 1.2.0" && git -C /tmp/tap push
|
|
```
|
|
Users get it with `brew upgrade mapsize`. Template:
|
|
`packaging/homebrew/mapsize.rb.in`.
|
|
|
|
Always pass `VERSION=`: otherwise it comes from `git describe`, which only
|
|
matches the tag when HEAD is exactly the tagged commit. `make release` and
|
|
the Homebrew formula stamp the version into the binary; `make build` and
|
|
`go install` use the value in `brand.go`, which is why step 1 updates it.
|
|
|
|
The snapshot format is stable at version 1: a format change must bump
|
|
`snapshot.Version` and keep the reader for version 1.
|
|
|
|
## Test data
|
|
|
|
`treegen` creates synthetic trees:
|
|
|
|
```sh
|
|
bin/treegen --out /tmp/t --directories 50000 --files 1000000 --max-depth 20 --sparse --unicode
|
|
bin/mapsize /tmp/t
|
|
```
|
|
|
|
## Benchmarks
|
|
|
|
```sh
|
|
make benchmark # Go micro-benchmarks (layout, render, filter, scan)
|
|
scripts/bench-scan.sh /path 1 2 4 8 # wall time and peak RSS per worker count
|
|
sudo DROP_CACHES=1 scripts/bench-scan.sh /path # cold-cache runs
|
|
MAPSIZE_MEM_ROOT=/path go test ./internal/scan -run TestMemoryPerNode -v
|
|
```
|
|
|
|
Paste results into PERFORMANCE.md with the machine description. Never edit
|
|
numbers by hand.
|
|
|
|
## Terminal restoration checks
|
|
|
|
```sh
|
|
MAPSIZE_DEBUG_PANIC=ui bin/mapsize . # panics on the first key press
|
|
MAPSIZE_DEBUG_PANIC=scanner bin/mapsize / # panics in a scanner goroutine
|
|
stty -a # echo/icanon must be back on
|
|
```
|
|
|
|
## Profiling
|
|
|
|
```sh
|
|
bin/mapsize --no-ui --cpuprofile cpu.prof --memprofile mem.prof /path
|
|
go tool pprof -http=: cpu.prof
|
|
```
|
|
|
|
`--log FILE --log-level debug` writes a log without disturbing the TUI.
|
|
Paths are logged only at `debug`/`trace` level.
|
|
|
|
## Layout
|
|
|
|
See ARCHITECTURE.md. Rules of thumb:
|
|
|
|
* `internal/treemap` and `internal/filter` must not import UI packages.
|
|
* Only `internal/platform` may contain OS-specific code (build tags).
|
|
* All strings derived from filenames go through `textutil.Sanitize` before
|
|
reaching a terminal.
|