From 5d49955998e6c64e33f609ab166113fc056bba5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Tue, 6 Apr 2021 09:14:25 +0100 Subject: [PATCH] README: document commands While at it, slightly tweak and update the rest of the markdown docs. --- CONTRIBUTING.md | 26 ++++++++++++++++---------- README.md | 6 ++++-- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50825fa..628e8dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ 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 -short` to skip some extra and slow sanity checks * Use `go test -run Script/foo` to just run `testdata/scripts/foo.txt` ### Development tips @@ -51,8 +51,8 @@ the hash of the operation's output. For more, read ### 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](https://golang.org/x/perf/cmd/benchstat): +fairly simple main program with and without caching. Here is an example of how +to use the benchmark with [benchstat](https://golang.org/x/perf/cmd/benchstat): # Run the benchmark six times with five iterations each. go test -run=- -bench=. -count=6 -benchtime=5x >old.txt @@ -77,12 +77,18 @@ running the benchmark. The provided example should be a sane default, and each 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 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 sys-time/op new sys-time/op delta - Build-8 1.18s ± 6% 1.22s ± 8% ~ (p=0.310 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 user-time/op new user-time/op delta - Build-8 9.82s ± 6% 10.01s ± 7% ~ (p=0.485 n=6+6) + 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) diff --git a/README.md b/README.md index a346053..47ebc48 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ Obfuscate Go code by wrapping the Go toolchain. Requires Go 1.16 or later. garble build [build flags] [packages] +The tool also supports `garble test` to run tests with obfuscated code, +and `garble reverse` to de-obfuscate text such as stack traces. See `garble -h` for up to date usage information. ### Purpose @@ -17,7 +19,7 @@ The tool is designed to be: * Coupled with `cmd/go`, to support modules and build caching * Deterministic and reproducible, given the same initial source code -* Reversible given the original source, to deobfuscate panic stack traces +* Reversible given the original source, to de-obfuscate panic stack traces ### Mechanism @@ -64,7 +66,7 @@ Go binary. This includes line numbers, filenames, and code in the runtime that prints panics, fatal errors, and trace/debug info. All in all this can make binaries 2-5% smaller in our testing. -Note: if `-tiny` is passed, no panics, fatal errors will ever be printed, but they can +Note: if `-tiny` is passed, no panics or fatal errors will ever be printed, but they can still be handled internally with `recover` as normal. In addition, the `GODEBUG` environmental variable will be ignored.