all: update the docs a bit

Rework the features section in the README, leaving optional features at
the end of the list. Simplify the caveats list, too; the build cache and
exported field/method bits only need one point each. Overall, the
section was far too wordy for little reason.

Also redo the help text a bit. There's now a line to briefly introduce
the tool, as well as a link to the README with all the details. Finally,
the flags have shorter and more consistent help strings.

While at it, remove two unused global vars as spotted by staticcheck.

README.md

@@ -2,8 +2,8 @@
 
 	GO111MODULE=on go get mvdan.cc/garble
 
-Obfuscate a Go build. Requires Go 1.15 or later, since Go 1.14 uses an entirely
+Obfuscate Go code by wrapping the Go toolchain. Requires Go 1.15 or later, since
-different object format.
+Go 1.14 uses an entirely different object format.
 
 	garble build [build flags] [packages]
 
@@ -29,10 +29,10 @@ order to:
 * Replace package paths with short base64 hashes
 * Remove all [build](https://golang.org/pkg/runtime/#Version) and [module](https://golang.org/pkg/runtime/debug/#ReadBuildInfo) information
 * Strip filenames and shuffle position information
-* Obfuscate literals, if the `-literals` flag is given
 * Strip debugging information and symbol tables
-* Expose additional functions in the runtime that can optionally hide
+* Obfuscate literals, if the `-literals` flag is given
-  information during execution
+* Expose [additional functions](#runtime-api) in the runtime package that can
+  optionally hide information during execution
 
 ### Options
 
@@ -45,26 +45,16 @@ packages to garble, set `GOPRIVATE`, documented at `go help module-private`.
 Most of these can improve with time and effort. The purpose of this section is
 to document the current shortcomings of this tool.
 
-* The `-a` flag for `go build` is required, since `-toolexec` doesn't work well
+* Build caching is not supported, so large projects will likely be slow to
-  with the build cache; see [golang/go#27628](https://github.com/golang/go/issues/27628).
+  build. See [golang/go#41145](https://github.com/golang/go/issues/41145).
-
-* Since no caching at all can take place right now (see the link above), fast
-  incremental builds aren't possible. Large projects might be slow to build.
-
-* Deciding what method names to garble is always going to be difficult, due to
-  interfaces that could be implemented up or down the package import tree. At
-  the moment, exported methods are never garbled.
 
-* Similarly to methods, exported struct fields are difficult to garble, as the
+* Exported methods and fields are never garbled at the moment, since they could
-  names might be relevant for reflection work like `encoding/json`. At the
+  be required by interfaces and reflection. This area is a work in progress.
-  moment, exported methods are never garbled.
 
 * Functions implemented outside Go, such as assembly, aren't garbled since we
   currently only transform the input Go source.
 
-* ~~Since `garble` forces `-trimpath`, plugins built with `-garble` must be loaded
+* Go plugins are not currently supported; see [#87](https://github.com/mvdan/garble/issues/87).
-  from Go programs built with `-trimpath` too.~~ Plugins currently do not always
-  work with well with `garble`; see [#87](https://github.com/mvdan/garble/issues/87).
 
 ### Runtime API
 

import_obfuscation.go

@@ -538,7 +538,7 @@ func garbleSymData(data []byte, privImports privateImports, garbledImports map[s
 	return buf.Bytes()
 }
 
-//createImportPathData creates reflection data for an
+// createImportPathData creates reflection data for an
 // import path
 func createImportPathData(importPath string) []byte {
 	l := 3 + len(importPath)

internal/literals/literals.go

@@ -12,11 +12,7 @@ import (
 	ah "mvdan.cc/garble/internal/asthelper"
 )
 
-var (
+var usesUnsafe bool
-	usesUnsafe     bool
-	universalTrue  = types.Universe.Lookup("true")
-	universalFalse = types.Universe.Lookup("false")
-)
 
 func randObfuscator() obfuscator {
 	randPos := mathrand.Intn(len(obfuscators))

main.go

@@ -46,27 +46,30 @@ var (
 
 func init() {
 	flagSet.Usage = usage
-	flagSet.BoolVar(&flagGarbleLiterals, "literals", false, "Encrypt all literals with AES, currently only literal strings are supported")
+	flagSet.BoolVar(&flagGarbleLiterals, "literals", false, "Obfuscate literals such as strings")
 	flagSet.BoolVar(&flagGarbleTiny, "tiny", false, "Optimize for binary size, losing the ability to reverse the process")
-	flagSet.StringVar(&flagDebugDir, "debugdir", "", "Write the garbled source to a given directory: '-debugdir=./debug'")
+	flagSet.StringVar(&flagDebugDir, "debugdir", "", "Write the garbled source to a directory, e.g. -debugdir=out")
-	flagSet.StringVar(&flagSeed, "seed", "", "Provide a custom base64-encoded seed: '-seed=o9WDTZ4CN4w=' \nFor a random seed provide: '-seed=random'")
+	flagSet.StringVar(&flagSeed, "seed", "", "Provide a base64-encoded seed, e.g. -seed=o9WDTZ4CN4w=\nFor a random seed, provide -seed=random")
 }
 
 func usage() {
 	fmt.Fprintf(os.Stderr, `
-Usage of garble:
+Garble obfuscates Go code by wrapping the Go toolchain.
 
-garble [flags] build [build flags] [packages]
+Usage:
 
-The tool supports wrapping the following Go commands - run "garble cmd [args]"
+	garble [flags] build [build flags] [packages]
-instead of "go cmd [args]" to add obfuscation:
 
-	build
+Aside from "build", the "test" command mirroring "go test" is also supported.
-	test
 
 garble accepts the following flags:
+
 `[1:])
 	flagSet.PrintDefaults()
+	fmt.Fprintf(os.Stderr, `
+
+For more information, see https://github.com/mvdan/garble.
+`[1:])
 	os.Exit(2)
 }
 

testdata/scripts/help.txt

@@ -1,24 +1,24 @@
 ! garble
-stderr -count=1 'Usage of garble'
+stderr -count=1 'Usage'
-stderr 'garble cmd'
+stderr 'garble \[flags\] build'
 ! stderr 'usage: go build'
 ! stdout .
 
 ! garble -h
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stdout .
 
 ! garble help
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stdout .
 
 ! garble build -h
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stderr 'usage: go build'
 ! stdout .
 
 ! garble -badflag
-stderr 'Usage of garble'
+stderr 'garble \[flags\] build'
 ! stdout .
 
 ! garble badcmd