Skip to content

docs: fix go tool nm usage in binary-size.md #2457

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kolyshkin wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: fix go tool nm usage in binary-size.md #2457

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/v3/binary-size.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,13 @@ go build -trimpath -ldflags="-s -w" -o myapp ./cmd/myapp
ls -lh myapp
```

Use the Go toolchain to inspect what is in the binary:
Use the Go toolchain to inspect what is in the binary. Note that `go tool nm`
needs the symbol table, so run it on a binary built without `-ldflags="-s -w"`:

```sh-session
go build -trimpath -o myapp ./cmd/myapp
go version -m myapp
go tool nm -size myapp | sort -nr | head -40

@coilysiren coilysiren Oct 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kolyshkin can you should me a before and after of the command output?

@kolyshkin kolyshkin Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please try it yourself -- all you need is Go installed.

Basically, "before" doesn't work because the binary is stripped, and even when it's not, the output is sorted by address (rather than size).

After is what the original author had in mind (I guess).

@coilysiren coilysiren Oct 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😅 the purpose of the ask is to provide documentation, not for me to see the diff personally

Here's a format for you

before

# input
ls "~/camels"| rg water | xargs drink.sh

# output
wow I love this, but it wasnt much

after

# input
ls "~/camels" | rg liquid | xargs drink.sh

# output
this was okay, and I feel satisfied

@kolyshkin kolyshkin Oct 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure. Using examples/example-cli from this repo (go1.26):

before

# input
go build -trimpath -ldflags="-s -w" -o myapp .
go tool nm -size myapp | sort -nr | head -5

# output
reading myapp: no symbol section
reading myapp: no symbols

Even with an unstripped binary, sort -nr sorts by the first column (the address), so the "largest" symbols are zero-sized:

# input
go build -trimpath -o myapp .
go tool nm -size myapp | sort -nr | head -5

# output
  771700          0 d runtime.enoptrbss
  771700          0 d runtime.end
  771700          0 d runtime.ecovctrs
  771700          0 d runtime.covctrs
  760700      69632 D runtime.cgroupScratch

after

# input
go build -trimpath -o myapp .
go tool nm -size -sort size myapp | head -5

# output
  6ee248     228144 r go:func.*
  745380      93464 D runtime.mheap_
  760700      69632 D runtime.cgroupScratch
  7414c0      16064 D runtime.semtable
  5469e0      14161 T github.com/urfave/cli/v3.(*Command).run

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

## Practical Checks
Expand Down
Loading