Answer to the question
Go's linker performs dead code elimination through a reachability analysis algorithm that constructs a dependency graph starting from the program's entry points: main.main and all package init functions. It traverses the call graph, marking every function and global variable that is statically referenced, then discards unmarked symbols before writing the final binary. This process is conservative; if a function's address is taken and stored in an interface, passed to reflect.Value.Call, or referenced via assembly code or the //go:linkname directive, the linker must retain it because it cannot prove the function won't be invoked at runtime. Additionally, CGO exported functions and methods registered for reflection-based decoding (such as json.Unmarshal into an interface{} that dynamically dispatches to concrete types) may force retention of otherwise unreachable code paths. The optimization is enabled by default and operates across packages, meaning unused code in third-party dependencies can be eliminated if no references exist from the application's reachable code.
Situation from life
A platform team noticed that their CLI tool had ballooned to 47MB after introducing a comprehensive observability library that supported multiple telemetry backends (Jaeger, Zipkin, Prometheus), even though the service only exported Prometheus metrics. The problem stemmed from the library's monolithic architecture where importing the package initialized global registries for all backends, pulling in expensive dependencies like Kafka clients and gRPC libraries for Zipkin that were never actually used.
The first solution considered was manually maintaining a fork of the library with unused backends removed. While this would guarantee elimination of dead code, it created an unacceptable maintenance burden requiring manual security patches and merge conflict resolution with upstream.
The second approach tested was applying UPX compression to the binary, which reduced the size to 13MB. However, this introduced significant startup latency due to runtime decompression and triggered false positives in enterprise antivirus scanners, making it unsuitable for production deployment.
The third option involved using ldflags="-s -w" to strip debug information and symbol tables. This yielded only a 3MB reduction without addressing the actual machine code bloat, as the unused backend implementations remained in the binary.
The team chose to restructure their code to avoid the problematic import. They defined a minimal metrics interface in the core application, then moved the concrete Prometheus implementation into a sub-package imported only by main. This ensured that the unused Zipkin and Jaeger code paths were not referenced by any symbol reachable from main.main or init functions. They also audited for any reflect.Type method lookups that might accidentally retain backend constructors. This architectural change allowed Go's linker to perform aggressive tree shaking.
The result was a reduction to 9MB without external compression, faster CI artifact uploads, and reduced container startup times, while preserving the ability to upgrade the observability library without patching.
What candidates often miss
Why does the linker retain functions that are only referenced inside code blocks guarded by compile-time constant false conditions, such as if false?
Go's linker operates at the symbol dependency level, not the basic block level within functions. While the compiler's SSA (Static Single Assignment) optimization passes may eliminate dead branches like if false, if the function containing the branch is itself reachable, any function it calls directly (not through conditional logic) creates a reference edge in the object file. More critically, if a package is imported, its init function is unconditionally considered a root of the reachability graph. Therefore, any function called by an init function is retained regardless of whether the package's public API is ever used by the application. Developers often assume that unused imports are harmless, but they can significantly bloat binaries if those imports perform heavy initialization.
How does taking the address of a function with &fn affect dead code elimination compared to calling it directly, and why might this cause unexpected binary size increases in callback registries?
When a function's address is taken and stored in a global variable or data structure at package initialization time (e.g., var defaultHandler = &unusedFunction), the linker must mark unusedFunction as reachable because the assignment creates a static data reference that the linker cannot distinguish from dynamic usage. Unlike direct function calls, which can be eliminated if the calling function itself becomes unreachable, address-taking creates a persistent reference in the binary's data section. This often surprises developers implementing plugin systems or HTTP handler registries using package-level map[string]func() variables, as every function added to the map survives dead code elimination even if the map is never accessed.
What distinguishes the //go:linkname directive's impact on symbol retention compared to standard exported functions, and why might linking to an internal standard library function prevent elimination of an entire package?
The //go:linkname directive allows package A to reference a symbol from package B using the linker's symbol name rather than the language's export mechanism. When a symbol is the target of a //go:linkname directive from any package in the build, the linker treats it as a root of the reachability graph, similar to main.main. This is because the directive is frequently used by the runtime and standard library to access unexported functions across package boundaries (e.g., runtime calling syscall internals). Unlike regular exported functions, which are only retained if there is a transitive call path from main or init, linkname targets survive even if the package containing the directive is never imported by the application. Consequently, user code that links to internal standard library symbols can inadvertently force the linker to retain large portions of the runtime or syscall packages that would otherwise be eliminated.