Why does `g++ -lgeo main.o` fail with undefined references to libgeo.a symbols while `g++ main.o -lgeo` links?
answer
- left to right, one pass
- archives only fill current holes
- users before providers
- group or repeat for cycles
- -L is a directory, -l a name
basics
~20 sThe GNU linker reads inputs left to right and extracts archive members only for symbols already undefined at that point. With -lgeo first nothing is undefined yet, so no member is pulled and main.o's references stay unresolved.
solid answer
~40 sGCC passes `-l` straight to the linker, and the GNU linker processes objects and libraries **in command-line order**. A static archive like `libgeo.a` is a bag of object files; when the linker reaches it, it extracts only the members that define a symbol **currently undefined**, then moves on and does not come back. In `g++ -lgeo main.o` the archive is scanned before `main.o` has introduced any references, so nothing is extracted, and the `undefined reference to` errors appear when `main.o` arrives. The rule is that a library goes **after** everything that uses it: `g++ main.o -lgeo -lmath` when `libgeo` calls into `libmath`. Mutually dependent archives need `-Wl,--start-group ... -Wl,--end-group` or a repeated `-l`. `-L dir` only adds search directories; `-lgeo` finds `libgeo.so` or `libgeo.a` there, preferring the shared one unless `-static` is given.
code
bash · 4 linesg++ -c main.cpp
g++ -lgeo -lmath main.o -L build/lib -o app # fails: archives scanned before any reference exists
g++ main.o -L build/lib -lgeo -lmath -o app # links: users first, then libgeo, then what libgeo needs
g++ main.o -L build/lib -Wl,--start-group -lgeo -lmath -Wl,--end-group -o app # for a libgeo <-> libmath cyclego deeper
Know that libraries go after the objects that use them and that -L adds a directory while -l names a library.
Explain the single left-to-right pass and why an archive member is only extracted to resolve a symbol already undefined.
Untangle dependent and cyclic archives with ordering, groups or --whole-archive, and prove the resolution with a map file or symbol trace.
Make link order a property the build system derives from declared dependencies rather than something people hand-edit on command lines.
## The symptom A program that linked yesterday stops linking after a static library is added or a link line is reordered. The GNU linker reports `undefined reference to` followed by the demangled name of each missing function, such as `geo::distance(geo::Point, geo::Point)`, and the object and function that used it. The library is there, `nm -C libgeo.a` shows the function defined, and yet the GNU linker reports it missing. The cause is almost always **where `-lgeo` sits on the command line**. ## How the GNU linker reads its inputs GCC's manual describes `-l` precisely: the option is passed directly to the linker, and the linker searches and processes libraries and object files **in the order they are specified**. Its own example: `foo.o -lz bar.o` searches `z` after `foo.o` but before `bar.o`, so if `bar.o` refers to functions in `z`, those functions may not be loaded. The mechanism behind that sentence: 1. The linker keeps a set of **undefined symbols**, initially empty. 2. An **object file** on the command line is always included in full; its definitions resolve entries in the set and its references add new ones. 3. A **static archive** (`lib<name>.a`) is a collection of object files with an index. When the linker reaches it, it extracts only the members that define a symbol currently in the undefined set, repeating within that archive until no more members help, and then **moves on**. 4. Nothing goes back to an earlier archive. A reference that appears later stays undefined unless a later input defines it. So `g++ -lgeo main.o` scans `libgeo.a` while the set is empty, takes nothing, and only then reads `main.o`, which needs `geo::distance`. ## Ordering rules that follow - Put libraries **after** the objects that use them: `g++ main.o util.o -lgeo`. - When libraries depend on each other, put the **user before the provider**: if `libgeo` calls `libmath`, write `-lgeo -lmath`. - When two archives depend on each other in a cycle, wrap them: `-Wl,--start-group -lgeo -lmath -Wl,--end-group` makes the GNU linker rescan the group until nothing new resolves, at some link-time cost. Repeating a library (`-lgeo -lmath -lgeo`) works for simple cycles. - `-Wl,option` passes an option through the driver; commas split into separate arguments, so `-Wl,-Map,app.map` asks for a map file showing which archive members were pulled and why. ## -L, -l and which file is found | Option | Meaning | |---|---| | `-L dir` | add `dir` to the directories searched for `-l` | | `-lgeo` | look for `libgeo.so` or `libgeo.a` in those directories and the standard ones | | `-static` | prevent linking with shared libraries | | `-l:libgeo.a` | GNU linker spelling for an exact file name | The manual's rule for the choice: if both a static and a shared library are found, the linker **prefers the shared library** unless `-static` is used. A team that believes it links `libgeo.a` may in fact depend on `libgeo.so` at run time. ## Shared libraries and order A shared library does not lose symbols the way an archive does, so order matters less for it. It can still matter: some distributions configure the linker with `--as-needed`, which records a shared library as a dependency only if it satisfies a reference **already seen**, so `-lgeo main.o` can drop the dependency and fail the same way. ## A diagnosis routine - Run `nm -C libgeo.a | grep distance` to confirm the definition exists, with the expected signature and namespace. - Read the exact link line with `g++ -v` and check that `-lgeo` comes after every user. - Ask the GNU linker who references and defines the symbol with `-Wl,--trace-symbol=<mangled name>`. - If the names differ only in mangling, for example a C function declared without `extern "C"`, the problem is a declaration mismatch, which belongs to the compilation model rather than to link order. ## Objects that are never pulled Order explains one more surprise. An archive member that only **registers itself** through a static constructor, such as a plugin or test registry, defines nothing anyone references, so the linker never extracts it and its constructor never runs. Linking that archive with `-Wl,--whole-archive -lplugins -Wl,--no-whole-archive` includes every member regardless.
- Why does the order rarely matter on a link line made only of object files?Object files named on the command line are always included in full, so every definition they contain is available no matter where it appears. Only archive members are selected on demand, at the moment the linker reaches the archive.
- When is -Wl,--whole-archive the right tool?When an archive contains objects that nothing references by name but that must run, such as self-registering plugins or test cases whose static constructors add them to a registry. It forces every member in; wrap it with `--no-whole-archive` so later libraries are not affected.
- The linker searches every library for every symbol, so order on the link line does not matter.
- -L tells the linker which library to link.
- -lgeo always picks libgeo.a when both libgeo.a and libgeo.so exist.
- A library should come before the objects that use it.
- Undefined references after adding a library mean the library was built with a different compiler.