Browse Source

prepare for the first release (#264)

First, write a changelog file. We will use GitHub releases, but the
content in those is not stored in git nor is it portable or machine
readable. The canonical place for the changelog is here.

Second, disable 'garble test', as it is entirely broken. Issue #241
tracks fixing and re-enabling it, which will most likely happen for the
next release.

Third, disable the undocumented 'garble list'. This was added as part of
'garble reverse', but it never got used. I can't think of any reason why
any end user would prefer it over 'go list', either.

'garble reverse' remains enabled, but undocumented as it isn't fully
functional yet. Until it supports position information, it's not
particularly useful to end users. But it's not broken either, so it can
remain where it is.

Fourth, update the '-tiny' size reduction numbers in the README. Since
we removed the in-place modification of object files, we are no longer
able to do such an aggressive stripping of info. Garble itself drops in
size by 2%, so replace the old 6-10% estimate by 2-5%. We probably will
gain some of this back in the near future.

Finally, fix the indentation formatting of the README to consistently
use tabs.
Daniel Martí 1 year ago
parent
commit
2a9c0b7bf4
3 changed files with 36 additions and 18 deletions
  1. 20 0
      CHANGELOG.md
  2. 15 15
      README.md
  3. 1 3
      main.go

+ 20 - 0
CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+This is the first release of Garble. It supports Go 1.15.x and 1.16.x.
+
+It ships all the major features that have worked for the past year, including:
+
+* Obfuscation of all names, except methods and reflect targets
+* Obfuscation of package import paths and position information
+* Stripping of build and module information
+* Support for Go modules
+* Reproducible and cacheable builds
+* Stripping of extra information via `-tiny`
+* Literal obfuscation via `-literals`
+
+Known bugs:
+
+* obfuscating the standard library with `GOPRIVATE=*` is not well supported yet
+* `garble test` is temporarily disabled, as it is currently broken

+ 15 - 15
README.md

@@ -36,7 +36,7 @@ order to:
 
 By default, the tool obfuscates the packages under the current module. If not
 running in module mode, then only the main package is obfuscated. To specify
-what packages to obfuscate, set `GOPRIVATE`, documented at `go help module-private`.
+what packages to obfuscate, set `GOPRIVATE`, documented at `go help private`.
 
 Note that commands like `garble build` will use the `go` version found in your
 `$PATH`. To use different versions of Go, you can
@@ -53,10 +53,10 @@ You can also declare a function to make multiple uses simpler:
 
 ```sh
 $ withgo() {
-        local gocmd=go${1}
-        shift
+	local gocmd=go${1}
+	shift
 
-        PATH=$(${gocmd} env GOROOT)/bin:${PATH} "$@"
+	PATH=$(${gocmd} env GOROOT)/bin:${PATH} "$@"
 }
 $ withgo 1.15.8 garble build
 ```
@@ -75,23 +75,23 @@ to document the current shortcomings of this tool.
 * Go plugins are not currently supported; see [#87](https://github.com/burrowers/garble/issues/87).
 
 * There are cases where garble is a little too agressive with obfuscation, this may lead to identifiers getting obfuscated which are needed for reflection, e.g. to parse JSON into a struct; see [#162](https://github.com/burrowers/garble/issues/162). To work around this you can pass a hint to garble, that an type is used for reflection via passing it to `reflect.TypeOf` or `reflect.ValueOf` in the same file:
-    ```go
-    // this is used for parsing json
-    type Message struct {
-        Command string
-        Args    string
-    }
+	```go
+	// this is used for parsing json
+	type Message struct {
+		Command string
+		Args    string
+	}
 
-    // never obfuscate the Message type
-    var _ = reflect.TypeOf(Message{})
-    ```
+	// never obfuscate the Message type
+	var _ = reflect.TypeOf(Message{})
+	```
 
 ### Tiny Mode
 
 When the `-tiny` flag is passed, extra information is stripped from the resulting
-Go binary. This includes line numbers, filenames, and code in the runtime the
+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
-6-10% smaller in our testing.
+2-5% smaller in our testing.
 
 Note: if `-tiny` is passed, no panics, fatal errors will ever be printed, but they can
 still be handled internally with `recover` as normal. In addition, the `GODEBUG`

+ 1 - 3
main.go

@@ -68,8 +68,6 @@ Usage:
 
 	garble [flags] build [build flags] [packages]
 
-Aside from "build", the "test" command mirroring "go test" is also supported.
-
 garble accepts the following flags:
 
 `[1:])
@@ -247,7 +245,7 @@ func mainErr(args []string) error {
 		return nil
 	case "reverse":
 		return commandReverse(args)
-	case "build", "test", "list":
+	case "build":
 		cmd, err := toolexecCmd(command, args)
 		if err != nil {
 			return err