Linkers Lto

mohitmishra786/low-level-dev-skills/skills/binaries/linkers-lto

by mohitmishra786bdc58472fa9fNo license253 starsListed Oct 9, 2026Updated Oct 9, 2026Repository updated 3 months ago

Linker and Link-Time Optimisation (LTO) skill. Use when configuring GNU ld, gold, or lld linker flags, diagnosing link-order issues or undefined symbols at link time, enabling LTO safely in real projects, or understanding inter-module optimisation trade-offs. Activates on queries about linker flags, -flto, thin LTO, LTCG, --gc-sections, link order errors, weak symbols, or linker scripts.

Instructions onlySoftware Development

AI-generated overview

Guides linker selection, linker flags, link-order issues, LTO setup, and symbol visibility for GNU ld, gold, and lld.

What it does: This skill provides instructions for choosing among GNU ld, gold, and lld, and for applying common linker flags such as -Wl,--as-needed, --gc-sections, and RELRO options. It explains link-order rules for archives, including --start-group/--end-group, and covers enabling GCC and Clang LTO, including ThinLTO and CMake interprocedural optimization. It also addresses dead-code stripping, symbol visibility via -fvisibility=hidden and version scripts, common linker errors, and map-file generation. A companion reference file lists linker and LTO flags.
When to use it: Use it when configuring linker flags for GNU ld, gold, or lld, or when diagnosing link-time problems such as undefined references, duplicate or weak symbols, and circular archive dependencies. It also fits enabling LTO safely in real projects, reducing binary size with --gc-sections, and understanding linker scripts or inter-module optimization trade-offs.
Requirements: No scripts are shipped; it is instructions only. Following the examples requires a C/C++ toolchain with a linker (GNU ld, gold, or lld), GCC or Clang, and binutils tools such as ar, gcc-ar, and gcc-ranlib. No credentials or network access are needed.

Linkers and LTO

Purpose

Guide agents through linker selection, common linker flags, link-order issues, LTO setup, and symbol-visibility management.

Triggers

"I'm getting undefined reference at link time"
"How do I enable LTO for a real project?"
"Which linker should I use: ld, gold, or lld?"
"How do I reduce binary size with --gc-sections?"
"How do I write or understand a linker script?"
"I have duplicate symbol or weak symbol issues"

Workflow

1. Linker selection

bash

# Use lld with GCC or Clanggcc -fuse-ld=lld -o prog ...clang -fuse-ld=lld -o prog ...
# Check which linker is usedgcc -v -o prog main.c 2>&1 | grep 'Invoking'

# Use lld with GCC or Clanggcc -fuse-ld=lld -o prog ...clang -fuse-ld=lld -o prog ...
# Check which linker is usedgcc -v -o prog main.c 2>&1 | grep 'Invoking'

2. Essential linker flags

bash

# Pass linker flags via compiler driver:# -Wl,flag1,flag2   (comma-separated, no spaces)# -Wl,flag1 -Wl,flag2  (separate -Wl options)
gcc main.c -o prog \  -Wl,-rpath,/opt/mylibs/lib \     # runtime library search path  -Wl,--as-needed \                 # only link libraries that are actually used  -Wl,--gc-sections \               # remove unused sections (requires -ffunction-sections -fdata-sections)  -Wl,-z,relro \                    # mark relocations read-only after startup  -Wl,-z,now \                      # resolve all symbols at startup (full RELRO)  -L/opt/mylibs/lib -lfoo

# Pass linker flags via compiler driver:# -Wl,flag1,flag2   (comma-separated, no spaces)# -Wl,flag1 -Wl,flag2  (separate -Wl options)
gcc main.c -o prog \  -Wl,-rpath,/opt/mylibs/lib \     # runtime library search path  -Wl,--as-needed \                 # only link libraries that are actually used  -Wl,--gc-sections \               # remove unused sections (requires -ffunction-sections -fdata-sections)  -Wl,-z,relro \                    # mark relocations read-only after startup  -Wl,-z,now \                      # resolve all symbols at startup (full RELRO)  -L/opt/mylibs/lib -lfoo

3. Link order matters (GNU ld)

GNU ld processes archives left-to-right. A library must come after the objects that need it.

bash

# Wrong: libfoo provides symbols needed by main.ogcc main.o -lfoo libdep.a -o prog   # can fail if libdep.a needs libfoo
# Correct: dependencies after dependentsgcc main.o -lfoo -ldep -o prog
# If there are circular deps between archives:gcc main.o -Wl,--start-group -lfoo -lbar -Wl,--end-group -o prog# --start-group/--end-group: repeat search until no new symbols resolved

# Wrong: libfoo provides symbols needed by main.ogcc main.o -lfoo libdep.a -o prog   # can fail if libdep.a needs libfoo
# Correct: dependencies after dependentsgcc main.o -lfoo -ldep -o prog
# If there are circular deps between archives:gcc main.o -Wl,--start-group -lfoo -lbar -Wl,--end-group -o prog# --start-group/--end-group: repeat search until no new symbols resolved

4. LTO with GCC

bash

# Compilegcc -O2 -flto -ffunction-sections -fdata-sections -c foo.c -o foo.ogcc -O2 -flto -ffunction-sections -fdata-sections -c bar.c -o bar.o
# Link (must pass -flto again)gcc -O2 -flto -Wl,--gc-sections foo.o bar.o -o prog
# Archives: must use gcc-ar / gcc-ranlib, not plain argcc-ar rcs libfoo.a foo.ogcc-ranlib libfoo.a

# Compilegcc -O2 -flto -ffunction-sections -fdata-sections -c foo.c -o foo.ogcc -O2 -flto -ffunction-sections -fdata-sections -c bar.c -o bar.o
# Link (must pass -flto again)gcc -O2 -flto -Wl,--gc-sections foo.o bar.o -o prog
# Archives: must use gcc-ar / gcc-ranlib, not plain argcc-ar rcs libfoo.a foo.ogcc-ranlib libfoo.a

Parallel LTO:

bash

gcc -O2 -flto=auto foo.o bar.o -o prog   # uses jobservergcc -O2 -flto=4   foo.o bar.o -o prog    # 4 parallel jobs

gcc -O2 -flto=auto foo.o bar.o -o prog   # uses jobservergcc -O2 -flto=4   foo.o bar.o -o prog    # 4 parallel jobs

5. LTO with Clang / lld

bash

# Full LTOclang -O2 -flto -fuse-ld=lld foo.c bar.c -o prog
# ThinLTO (faster, nearly same quality)clang -O2 -flto=thin -fuse-ld=lld foo.c bar.c -o prog
# LTO with cmake: set globallyset(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON)   # enables -flto

# Full LTOclang -O2 -flto -fuse-ld=lld foo.c bar.c -o prog
# ThinLTO (faster, nearly same quality)clang -O2 -flto=thin -fuse-ld=lld foo.c bar.c -o prog
# LTO with cmake: set globallyset(CMAKE_INTERPROCEDURAL_OPTIMIZATION ON)   # enables -flto

ThinLTO caches work: subsequent builds that reuse unchanged modules are faster. Cache location: specify with -Wl,--thinlto-cache-dir=/tmp/thinlto-cache.

6. Dead-code stripping

bash

# Compile with per-function/per-data sectionsgcc -O2 -ffunction-sections -fdata-sections -c foo.c -o foo.o
# Link with garbage collectiongcc -Wl,--gc-sections foo.o -o prog
# Verify what was removedgcc -Wl,--gc-sections -Wl,--print-gc-sections foo.o -o prog 2>&1 | head -20

# Compile with per-function/per-data sectionsgcc -O2 -ffunction-sections -fdata-sections -c foo.c -o foo.o
# Link with garbage collectiongcc -Wl,--gc-sections foo.o -o prog
# Verify what was removedgcc -Wl,--gc-sections -Wl,--print-gc-sections foo.o -o prog 2>&1 | head -20

On macOS, the linker strips dead code by default (-dead_strip).

7. Symbol visibility

Controlling visibility reduces DSO size and enables better LTO:

bash

# Hide all symbols by default, export explicitlygcc -fvisibility=hidden -O2 -shared -fPIC foo.c -o libfoo.so
# In source, mark exports:__attribute__((visibility("default"))) int my_public_function(void);

# Hide all symbols by default, export explicitlygcc -fvisibility=hidden -O2 -shared -fPIC foo.c -o libfoo.so
# In source, mark exports:__attribute__((visibility("default"))) int my_public_function(void);

Or use a version script:

8. Common linker errors

Error	Cause	Fix
`undefined reference to 'foo'`	Missing library or wrong order	Add `-lfoo`; move after the object that needs it
`multiple definition of 'foo'`	Symbol defined in two TUs	Remove duplicate; use `static` or `extern`
`cannot find -lfoo`	Library not in search path	Add `-L/path/to/lib`; install dev package
`relocation truncated`	Address overflow in relocation	Use `-mcmodel=large`; restructure image
`version 'GLIBC_2.33' not found`	Binary needs newer glibc	Link statically or rebuild on older host
`circular reference`	Archives mutually depend	Use `--start-group`/`--end-group`

9. Linker map file

bash

# Generate a map file (shows symbol → section → file)gcc -Wl,-Map=prog.map -o prog foo.o bar.oless prog.map

# Generate a map file (shows symbol → section → file)gcc -Wl,-Map=prog.map -o prog foo.o bar.oless prog.map

Useful for debugging binary size and symbol placement.

For a comprehensive linker and LTO flags reference, see references/flags.md [blocked].

Related skills

Use skills/binaries/elf-inspection for examining the resulting binary
Use skills/compilers/gcc or skills/compilers/clang for compile-phase LTO flags
Use skills/binaries/binutils for ar, strip, objcopy

Source and attribution

Source:mohitmishra786/low-level-dev-skillsinskills/binaries/linkers-ltoat commitbdc5847

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Linker	Invocation	Strengths
GNU ld (BFD)	default on Linux	Universal, stable
gold	`-fuse-ld=gold`	Faster than ld for C++; supports LTO plugins
lld (LLVM)	`-fuse-ld=lld`	Fastest, parallel, required for Clang LTO

Linkers Lto

Linkers and LTO

Purpose

Triggers

Workflow

1. Linker selection

2. Essential linker flags

3. Link order matters (GNU ld)

4. LTO with GCC

5. LTO with Clang / lld

6. Dead-code stripping

7. Symbol visibility

8. Common linker errors

9. Linker map file

Related skills

Source and attribution

More from mohitmishra786/low-level-dev-skills

Zig Debugging

Simd Intrinsics

Zig Cross

Rustc Basics

Zig Cinterop

Zig Build System

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices