--warn-backrefs

--warn-backrefs gives a warning when an undefined symbol reference is resolved by a definition in an archive to the left of it on the command line.

A linker such as GNU ld makes a single pass over the input files from left to right maintaining the set of undefined symbol references from the files loaded so far. When encountering an archive or an object file surrounded by --start-lib and --end-lib that archive will be searched for resolving symbol definitions; this may result in input files being loaded, updating the set of undefined symbol references. When all resolving definitions have been loaded from the archive, the linker moves on the next file and will not return to it. This means that if an input file to the right of a archive cannot have an undefined symbol resolved by a archive to the left of it. For example:

ld def.a ref.o

will result in an undefined reference error. If there are no cyclic references, the archives can be ordered in such a way that there are no backward references. If there are cyclic references then the --start-group and --end-group options can be used, or the same archive can be placed on the command line twice.

LLD remembers the symbol table of archives that it has previously seen, so if there is a reference from an input file to the right of an archive, LLD will still search that archive for resolving any undefined references. This means that an archive only needs to be included once on the command line and the --start-group and --end-group options are redundant.

A consequence of the differing archive searching semantics is that the same linker command line can result in different outcomes. A link may succeed with LLD that will fail with GNU ld, or even worse both links succeed but they have selected different objects from different archives that both define the same symbols.

The warn-backrefs option provides information that helps identify cases where LLD and GNU ld archive selection may differ.

% ld.lld --warn-backrefs ... -lB -lA ld.lld: warning: backward reference detected: system in A.a(a.o) refers to B.a(b.o)

% ld.lld --warn-backrefs ... --start-lib B/b.o --end-lib --start-lib A/a.o --end-lib ld.lld: warning: backward reference detected: system in A/a.o refers to B/b.o

# To suppress the warning, you can specify --warn-backrefs-exclude=<glob> to match B/b.o or B.a(b.o)

The --warn-backrefs option can also provide a check to enforce a topological order of archives, which can be useful to detect layering violations (albeit unable to catch all cases). There are two cases where GNU ld will result in an undefined reference error:

• If adding the dependency does not form a cycle: conceptually A is higher level library while B is at a lower level. When you are developing an application P which depends on A, but does not directly depend on B, your link may fail surprisingly with undefined symbol: symbol_defined_in_B if the used/linked part of A happens to need some components of B. It is inappropriate for P to add a dependency on B since P does not use B directly.
• If adding the dependency forms a cycle, e.g. B->C->A ~> B. A is supposed to be at the lowest level while B is supposed to be at the highest level. When you are developing C_test testing C, your link may fail surprisingly with undefined symbol if there is somehow a dependency on some components of B. You could fix the issue by adding the missing dependency (B), however, then every test (A_test, B_test, C_test) will link against every library. This breaks the motivation of splitting B, C and A into separate libraries and makes binaries unnecessarily large. Moreover, the layering violation makes lower-level libraries (e.g. A) vulnerable to changes to higher-level libraries (e.g. B, C).

Resolution:

• Add a dependency from A to B.
• The reference may be unintended and can be removed.
• The dependency may be intentionally omitted because there are multiple libraries like B. Consider linking B with object semantics by surrounding it with --whole-archive and --no-whole-archive.
• In the case of circular dependency, sometimes merging the libraries are the best.

There are two cases like a library sandwich where GNU ld will select a different object.

• A.a B A2.so: A.a may be used as an interceptor (e.g. it provides some optimized libc functions and A2 is libc). B does not need to know about A.a, and A.a may be pulled into the link by other part of the program. For linker portability, consider --whole-archive and --no-whole-archive.

• A.a B A2.a: similar to the above case but --warn-backrefs does not flag the problem, because A2.a may be a replicate of A.a, which is redundant but benign. In some cases A.a and B should be surrounded by a pair of --start-group and --end-group. This is especially common among system libraries (e.g. -lc __isnanl references -lm, -lc _IO_funlockfile references -lpthread, -lc __gcc_personality_v0 references -lgcc_eh, and -lpthread _Unwind_GetCFA references -lunwind).

  In C++, this is likely an ODR violation. We probably need a dedicated option for ODR detection.