docs(v2): add binary size guide and mkdocs navigation for v2 build tags by AdamMagued · Pull Request #2456 · urfave/cli

AdamMagued · 2026-10-05T00:32:37Z

What type of PR is this?

documentation

What this PR does / why we need it:

Adds a dedicated v2 binary size guide covering build flags (-trimpath, -ldflags="-s -w") and compile-time tags (urfave_cli_no_docs and urfave_cli_no_suggest), and registers it in mkdocs navigation.

Which issue(s) this PR fixes:

Fixes #2365

Special notes for your reviewer:

None.

Testing

Verified documentation structure and mkdocs YAML syntax. All package unit tests, vet checks, and binary size checks pass cleanly in sandbox isolation.

Release Notes

Add binary size optimization guide and build flag reference for v2

greptile-apps · 2026-10-05T00:35:24Z

Confidence Score: 4/5

[Low risk] Expands binary size optimization documentation.

The PR should not merge until the v3 custom-template guidance covers commands with ExtraInfo.

Findings

Custom printer can be bypassed ▶
Stripped binary has no symbols ▶
Symbols sorted by address ▶

Summary

The PR adds a v2 binary-size guide and navigation entry, and expands the v3 guide with build flags, linker diagnostics, feature-pruning examples, and compression trade-offs.

The new v2 symbol-inspection workflow needs an unstripped binary and a size-field sort.
The v3 custom-printer guidance misses the ExtraInfo help path.

_{Reviews (1) · Last reviewed commit: "docs: expand binary size optimization gu..."}

greptile-apps · 2026-10-05T00:35:27Z

+
+```sh-session
+go version -m myapp
+go tool nm -size myapp | sort -nr | head -40


Stripped binary has no symbols
The preceding build uses -s, which removes the symbol table from myapp. Running go tool nm on that binary reports no symbols, so readers cannot inspect allocations as instructed. The guide needs an unstripped build for this step.

greptile-apps · 2026-10-05T00:35:27Z

+
+```sh-session
+go version -m myapp
+go tool nm -size myapp | sort -nr | head -40


Symbols sorted by address
go tool nm -size prints the address before the size, so sort -nr ranks addresses, not footprints. Even with an unstripped binary, the first 40 results are not necessarily the largest symbols, making the size investigation misleading. Sort on the size field instead.

Suggested change

go tool nm -size myapp | sort -nr | head -40

go tool nm -size myapp | sort -k2,2nr | head -40

greptile-apps · 2026-10-05T00:35:27Z

+- Passing custom templates to the default help printer causes a panic. Applications
+  requiring custom template rendering must supply a custom `HelpPrinter`.


Custom printer can be bypassed
When a command has ExtraInfo, root help calls HelpPrinterCustom directly rather than the application's replacement HelpPrinter. With urfave_cli_no_template and a custom template, following this workaround still reaches the default printer and panics. These applications also need to replace HelpPrinterCustom or avoid that help path.

kolyshkin

The patch looks way too broad, changing lots of files at once, without explaining why, and is thus very hard to review.

If you can write more focused patch series, like:

add this;
fix that;
change the wording in such-and-such section

that would be easier to review.

AdamMagued · 2026-10-05T15:44:15Z

@kolyshkin I split the PR into five focused commits:

docs(v3): fix symbol sorting and clarify unstripped binary requirement for nm: fixes the go tool nm -size sort key (-k2,2nr instead of -nr) and notes that -s strips symbol tables.
docs(v3): document linker dead code elimination diagnostic with dumpdep: documents using go build -ldflags=-dumpdep to detect <ReflectMethod> when testing dead code elimination status.
docs(v3): clarify urfave_cli_no_template constraints and ExtraInfo handling: details template immutability, default printer panics, and the requirement to override HelpPrinterCustom when commands define ExtraInfo.
docs(v2): add binary size guide for v2 build tags: adds docs/v2/binary-size.md covering -trimpath, -ldflags="-s -w", and the v2 tags urfave_cli_no_docs and urfave_cli_no_suggest.
docs: register v2 binary size guide in mkdocs navigation: adds the v2 guide to mkdocs.yml.

I also dropped the generic UPX and pprof examples to keep the diff limited to urfave/cli specifics (+146 -21 total diff).

kolyshkin · 2026-10-05T19:03:18Z

+go tool nm -size myapp | sort -k2,2nr | head -40
 ```

+> **Note:** The `-s` flag strips the symbol table. Run `go tool nm` against


Which -s flag? I mean, I understand that you talk about ldflags from the previous step, but I doubt it's easy to get for every other reader.

kolyshkin · 2026-10-05T19:04:12Z


+> **Note:** The `-s` flag strips the symbol table. Run `go tool nm` against
+> an unstripped binary. `sort -k2,2nr` sorts by symbol size (the second column)
+> rather than address.


I think it does not need to be explained.

kolyshkin · 2026-10-05T19:04:55Z

-modules, since each one resolves versions independently — so check the
+modules, since each resolves versions independently; check the


How is this an improvement? You just change the text arbitrarily

kolyshkin · 2026-10-05T19:06:17Z

+The standard library `text/template` package evaluates template methods via
+dynamic reflection, triggering this linker behavior.


You repeat what was said a few lines above (in Reflection and Templates), why?

kolyshkin · 2026-10-05T19:06:34Z

+overhead is important, a compile-time approach, such as separate build
+configurations or changes to the library, would be required.


why the change?

kolyshkin · 2026-10-05T19:06:48Z

+Using `text/template` causes the Go linker to disable dead code elimination of
+exported methods for the whole program, since templates can invoke arbitrary


why the change?

kolyshkin · 2026-10-05T19:06:54Z

+exported methods for the whole program, since templates can invoke arbitrary
 methods by name (see [golang/go#72895](https://github.com/golang/go/issues/72895)).
-For larger programs, this can noticeably increase the binary size.
+For larger programs, this can noticeably increase binary size.


kolyshkin · 2026-10-05T19:07:18Z

+completion render without `text/template`, producing identical output,
+and dead code elimination remains active:


you just arbitrarily rephrased it, why?

kolyshkin

I would only leave commit 4 ("docs(v2): add binary size guide for v2 build tags") -- if we still care for v2 (do we)?

As for the rest, I would drop (or rework, considerably) it. It looks like the objective here was to maximize the amount of changes, and not fix the issues with the current doc.

Document compiler and linker flags (-trimpath, -ldflags="-s -w") and symbol table inspection using 'go tool nm -size' on unstripped binaries. Document v2 compile-time build tags 'urfave_cli_no_docs' and 'urfave_cli_no_suggest', their savings, and their transition to v3. Register docs/v2/binary-size.md under the v2 manual navigation in mkdocs.yml. Signed-off-by: AdamMagued <adamismailmageud@gmail.com>

AdamMagued · 2026-10-06T13:47:09Z

@kolyshkin I dropped the v3 documentation changes and squashed the branch into a single commit. This PR now keeps docs/v2/binary-size.md and the navigation entry in mkdocs.yml.

AdamMagued requested a review from a team as a code owner October 5, 2026 00:32

greptile-apps Bot reviewed Oct 5, 2026

View reviewed changes

kolyshkin suggested changes Oct 5, 2026

View reviewed changes

AdamMagued force-pushed the fix-issue-2365 branch from 97c61ec to b598d5c Compare October 5, 2026 15:43

kolyshkin reviewed Oct 5, 2026

View reviewed changes

kolyshkin suggested changes Oct 5, 2026

View reviewed changes

AdamMagued force-pushed the fix-issue-2365 branch from b598d5c to fa454e1 Compare October 6, 2026 13:43

AdamMagued changed the title ~~docs: expand binary size optimization guide and build flag details~~ docs(v2): add binary size guide and mkdocs navigation for v2 build tags Oct 6, 2026

	go tool nm -size myapp \| sort -nr \| head -40
	go tool nm -size myapp \| sort -k2,2nr \| head -40

		- Passing custom templates to the default help printer causes a panic. Applications
		requiring custom template rendering must supply a custom `HelpPrinter`.

		modules, since each one resolves versions independently — so check the
		modules, since each resolves versions independently; check the

		The standard library `text/template` package evaluates template methods via
		dynamic reflection, triggering this linker behavior.

		overhead is important, a compile-time approach, such as separate build
		configurations or changes to the library, would be required.

		Using `text/template` causes the Go linker to disable dead code elimination of
		exported methods for the whole program, since templates can invoke arbitrary

		completion render without `text/template`, producing identical output,
		and dead code elimination remains active:

Conversation

AdamMagued commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for your reviewer:

Testing

Release Notes

Uh oh!

greptile-apps Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Uh oh!

greptile-apps Bot Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 5, 2026

Choose a reason for hiding this comment

Uh oh!

kolyshkin left a comment

Choose a reason for hiding this comment

Uh oh!

AdamMagued commented Oct 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kolyshkin left a comment

Choose a reason for hiding this comment

Uh oh!

AdamMagued commented Oct 6, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AdamMagued commented Oct 5, 2026 •

edited

Loading

greptile-apps Bot commented Oct 5, 2026 •

edited

Loading