add the first benchmark and CONTRIBUTING doc

CONTRIBUTING.md

@@ -0,0 +1,66 @@
+## Contributing to Garble
+
+Thank you for your interest in contributing! Here are some ground rules:
+
+1. The tool's design decisions are in the [README](README.md)
+2. New features or major changes should be opened as an issue first
+3. Non-trivial contributions should be done in PRs with code review and CI
+4. We use the `#obfuscation` channel over at the [Gophers Slack](https://invite.slack.golangbridge.org/) to chat
+
+### Testing
+
+Just the usual `go test ./...`; many of the tests are in
+[testscript](https://godoc.org/github.com/rogpeppe/go-internal/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 run `testdata/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](https://lu4p.github.io/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](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
+
+	# 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)

bench_test.go

@@ -0,0 +1,54 @@
+// Copyright (c) 2020, Daniel Martí <mvdan@mvdan.cc>
+// See LICENSE for licensing information
+
+package main
+
+import (
+	"io/ioutil"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sync/atomic"
+	"testing"
+)
+
+// BenchmarkBuild is a parallel benchmark for 'garble build' on a fairly simple
+// main package with a handful of standard library depedencies.
+//
+// We use a real garble binary and exec it, to simulate what the real user would
+// run. The real obfuscation and compilation will happen in sub-processes
+// anyway, so skipping one exec layer doesn't help us in any way.
+//
+// At the moment, each iteration takes 1-2s on a laptop, so we can't make the
+// benchmark include any more features unless we make it significantly faster.
+func BenchmarkBuild(b *testing.B) {
+	tdir, err := ioutil.TempDir("", "garble-bench")
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer os.RemoveAll(tdir)
+
+	garbleBin := filepath.Join(tdir, "garble")
+	if err := exec.Command("go", "build", "-o="+garbleBin).Run(); err != nil {
+		b.Fatalf("building garble: %v", err)
+	}
+
+	// We collect extra metrics.
+	var n, userTime, systemTime int64
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			cmd := exec.Command(garbleBin, "build", "./testdata/bench")
+			if err := cmd.Run(); err != nil {
+				b.Fatal(err)
+			}
+
+			atomic.AddInt64(&n, 1)
+			atomic.AddInt64(&userTime, int64(cmd.ProcessState.UserTime()))
+			atomic.AddInt64(&systemTime, int64(cmd.ProcessState.SystemTime()))
+		}
+	})
+	b.ReportMetric(float64(userTime)/float64(n), "user-ns/op")
+	b.ReportMetric(float64(systemTime)/float64(n), "sys-ns/op")
+}

testdata/bench/main.go

@@ -0,0 +1,12 @@
+package main
+
+import "fmt"
+
+var globalVar = "global value"
+
+func globalFunc() { fmt.Println("global func body") }
+
+func main() {
+	fmt.Println(globalVar)
+	globalFunc()
+}