2.6 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
- Non-trivial contributions should be done in PRs with code review and CI
- We use the
#obfuscation
channel over at the Gophers Slack to chat
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 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.
Benchmarking
A build benchmark is available, to be able to measure the cost of builing a fairly simple main program. 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:
$ benchstat old.txt new.txt
name old time/op new time/op delta
Build-8 1.63s ± 6% 1.65s ± 6% ~ (p=0.699 n=6+6)
name old sys-time/op new sys-time/op delta
Build-8 1.18s ± 6% 1.22s ± 8% ~ (p=0.310 n=6+6)
name old user-time/op new user-time/op delta
Build-8 9.82s ± 6% 10.01s ± 7% ~ (p=0.485 n=6+6)