Skip to content

Commit

Permalink
README: clarify that we have no plans to exclude files or packages
Browse files Browse the repository at this point in the history
This is a common question in the issue tracker: burrowers#631, burrowers#777, burrowers#802, burrowers#844.
While here, tweak the wording and formatting in the section as well.
  • Loading branch information
mvdan authored and lu4p committed Apr 25, 2024
1 parent 9f82b2b commit c41f026
Showing 1 changed file with 11 additions and 4 deletions.
15 changes: 11 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,11 +157,11 @@ to document the current shortcomings of this tool.
be required by interfaces. This area is a work in progress; see
[#3](https://github.com/burrowers/garble/issues/3).

* Garble aims to automatically detect which Go types are used with reflection,
as obfuscating those types might break your program.
* Garble automatically detects which Go types are used with reflection
to avoid obfuscating them, as that might break your program.
Note that Garble obfuscates [one package at a time](#speed),
so if your reflection code inspects a type from an imported package,
and your program broke, you may need to add a "hint" in the imported package:
you may need to add a "hint" in the imported package to exclude obfuscating it:
```go
type Message struct {
Command string
Expand All @@ -172,13 +172,20 @@ to document the current shortcomings of this tool.
var _ = reflect.TypeOf(Message{})
```

* Aside from `GOGARBLE` to select patterns of packages to obfuscate,
and the hint above with `reflect.TypeOf` to exclude obfuscating particular types,
there is no supported way to exclude obfuscating a selection of files or packages.
More often than not, a user would want to do this to work around a bug; please file the bug instead.

* Go programs [are initialized](https://go.dev/ref/spec#Program_initialization) one package at a time,
where imported packages are always initialized before their importers,
and otherwise they are initialized in the lexical order of their import paths.
Since garble obfuscates import paths, this lexical order may change arbitrarily.

* Go plugins are not currently supported; see [#87](https://github.com/burrowers/garble/issues/87).
* Garble requires `git` to patch the linker. That can be avoided once go-gitdiff supports [non-strict patches](https://github.com/bluekeyes/go-gitdiff/issues/30).

* Garble requires `git` to patch the linker. That can be avoided once go-gitdiff
supports [non-strict patches](https://github.com/bluekeyes/go-gitdiff/issues/30).

### Contributing

Expand Down

0 comments on commit c41f026

Please sign in to comment.