From 8bc971e0a284c3b2f85faac498e87ed10a9103f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Mon, 11 Jul 2022 09:30:03 +0100 Subject: [PATCH] README: slightly tweak the wording around flags Make the literals section easier to follow by using the word "expression" more consistently. The tiny section was misleading as well, as the README made it seem like position information was stripped both with and without the flag. Clarify what happens with that information in each case. --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 04e87b4..7103da7 100644 --- a/README.md +++ b/README.md @@ -28,8 +28,8 @@ order to: * Replace as many useful identifiers as possible with short base64 hashes * Replace package paths with short base64 hashes +* Replace filenames and position information with short base64 hashes * Remove all [build](https://go.dev/pkg/runtime/#Version) and [module](https://go.dev/pkg/runtime/debug/#ReadBuildInfo) information -* Strip filenames and shuffle position information * Strip debugging information and symbol tables via `-ldflags="-w -s"` * [Obfuscate literals](#literal-obfuscation), if the `-literals` flag is given * Remove [extra information](#tiny-mode), if the `-tiny` flag is given @@ -54,19 +54,19 @@ $ PATH=$(go1.17.1 env GOROOT)/bin:${PATH} garble build ### Literal obfuscation Using the `-literals` flag causes literal expressions such as strings to be -replaced with more complex variants, resolving to the same value at run-time. +replaced with more complex expressions, resolving to the same value at run-time. This feature is opt-in, as it can cause slow-downs depending on the input code. -Literal expressions used as constants cannot be obfuscated, since they are +Literals used in constant expressions cannot be obfuscated, since they are resolved at compile time. This includes any expressions part of a `const` -declaration. +declaration, for example. ### 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 that -prints panics, fatal errors, and trace/debug info. All in all this can make binaries -2-5% smaller in our testing, as well as prevent extracting some more information. +With the `-tiny` flag, even more information is stripped from the Go binary. +Position information is removed entirely, rather than being obfuscated. +Runtime code which prints panics, fatal errors, and trace/debug info is removed. +All in all, this can make binaries 2-5% smaller. With this flag, no panics or fatal runtime errors will ever be printed, but they can still be handled internally with `recover` as normal. In addition, the