4.1 KiB
Contributing to Garble
Thank you for your interest in contributing! Here are some ground rules:
- The tool's design decisions are in the README
- New features or major changes should be opened as an issue first
- All contributions are done in PRs with at least one review and CI
- All changes that alter behavior (features, flags, bugs) need a test
- We use the
#obfuscation
channel over at the Gophers Slack to chat
When contributing for the first time, you should also add yourself to the AUTHORS file.
Testing
Just the usual go test ./...
; many of the tests are in
testscript under
testdata/script/
, which allows laying out files and shell-like steps to run as
part of the test.
Note that the tests do real builds, so they are quite slow; on an average
laptop, go test
can take over thirty seconds. Here are some tips:
- Use
go test -short
to skip some extra and slow sanity checks - Use
go test -run Script/foo
to just runtestdata/scripts/foo.txt
Development tips
To inject code into the syntax tree, don't write go/ast
nodes by hand; you can
generate them by typing Go source into tools such as
astextract.
Terminology
The Go toolchain, or simply the toolchain, refers to the go
command and
all of its components used to build programs, such as the compiler and linker.
An object file or archive file contains the output of compiling a Go package, later used to link a binary.
An import config is a temporary text file passed to the compiler via the
-importcfg
flag, which contains an object file path for each direct
dependency.
A build ID is a slash-separated list of hashes for a build operation, such as compiling a package or linking binary. The first component is the action ID, the hash of the operation's inputs, and the last component is the content ID, the hash of the operation's output. For more, read the docs in buildid.go
Benchmarking
A build benchmark is available, to be able to measure the cost of builing a fairly simple main program with and without caching. Here is an example of how to use the benchmark with benchstat:
# Run the benchmark six times with five iterations each.
go test -run=- -bench=. -count=6 -benchtime=5x >old.txt
# Make some change to the code.
git checkout some-optimization
# Obtain benchmark results once more.
go test -run=- -bench=. -count=6 -benchtime=5x >new.txt
# Obtain the final stats.
benchstat old.txt new.txt
It is very important to run the steps above on a quiet machine. Any background program that could use CPU or I/O should be closed, as it would likely skew the results; this includes browsers, chat apps, and music players.
A higher -benchtime
will mean more stable numbers, and a higher -count
will
mean more reliable statistical results, but both increase the overall cost of
running the benchmark. The provided example should be a sane default, and each
'go test' invocation takes about a minute on a laptop.
For example, below are the final results for a run where nothing was changed:
name old time/op new time/op delta
Build/Cache-8 165ms ± 3% 165ms ± 2% ~ (p=1.000 n=6+6)
Build/NoCache-8 1.26s ± 7% 1.27s ± 5% ~ (p=0.699 n=6+6)
name old bin-B new bin-B delta
Build/Cache-8 6.36M ± 0% 6.36M ± 0% ~ (all equal)
Build/NoCache-8 6.36M ± 0% 6.36M ± 0% ~ (all equal)
name old sys-time/op new sys-time/op delta
Build/Cache-8 205ms ± 6% 214ms ± 4% ~ (p=0.093 n=6+6)
Build/NoCache-8 512ms ± 6% 512ms ±12% ~ (p=0.699 n=6+6)
name old user-time/op new user-time/op delta
Build/Cache-8 829ms ± 1% 822ms ± 1% ~ (p=0.177 n=6+5)
Build/NoCache-8 8.44s ± 7% 8.55s ± 5% ~ (p=0.589 n=6+6)