1--warn-backrefs
2===============
3
4``--warn-backrefs`` gives a warning when an undefined symbol reference is
5resolved by a definition in an archive to the left of it on the command line.
6
7A linker such as GNU ld makes a single pass over the input files from left to
8right maintaining the set of undefined symbol references from the files loaded
9so far. When encountering an archive or an object file surrounded by
10``--start-lib`` and ``--end-lib`` that archive will be searched for resolving
11symbol definitions; this may result in input files being loaded, updating the
12set of undefined symbol references. When all resolving definitions have been
13loaded from the archive, the linker moves on the next file and will not return
14to it.  This means that if an input file to the right of a archive cannot have
15an undefined symbol resolved by a archive to the left of it. For example:
16
17    ld def.a ref.o
18
19will result in an ``undefined reference`` error. If there are no cyclic
20references, the archives can be ordered in such a way that there are no
21backward references. If there are cyclic references then the ``--start-group``
22and ``--end-group`` options can be used, or the same archive can be placed on
23the command line twice.
24
25LLD remembers the symbol table of archives that it has previously seen, so if
26there is a reference from an input file to the right of an archive, LLD will
27still search that archive for resolving any undefined references. This means
28that an archive only needs to be included once on the command line and the
29``--start-group`` and ``--end-group`` options are redundant.
30
31A consequence of the differing archive searching semantics is that the same
32linker command line can result in different outcomes. A link may succeed with
33LLD that will fail with GNU ld, or even worse both links succeed but they have
34selected different objects from different archives that both define the same
35symbols.
36
37The ``warn-backrefs`` option provides information that helps identify cases
38where LLD and GNU ld archive selection may differ.
39
40    | % ld.lld --warn-backrefs ... -lB -lA
41    | ld.lld: warning: backward reference detected: system in A.a(a.o) refers to B.a(b.o)
42
43    | % ld.lld --warn-backrefs ... --start-lib B/b.o --end-lib --start-lib A/a.o --end-lib
44    | ld.lld: warning: backward reference detected: system in A/a.o refers to B/b.o
45
46    # To suppress the warning, you can specify --warn-backrefs-exclude=<glob> to match B/b.o or B.a(b.o)
47
48The ``--warn-backrefs`` option can also provide a check to enforce a
49topological order of archives, which can be useful to detect layering
50violations (albeit unable to catch all cases). There are two cases where GNU ld
51will result in an ``undefined reference`` error:
52
53* If adding the dependency does not form a cycle: conceptually ``A`` is higher
54  level library while ``B`` is at a lower level. When you are developing an
55  application ``P`` which depends on ``A``, but does not directly depend on
56  ``B``, your link may fail surprisingly with ``undefined symbol:
57  symbol_defined_in_B`` if the used/linked part of ``A`` happens to need some
58  components of ``B``. It is inappropriate for ``P`` to add a dependency on
59  ``B`` since ``P`` does not use ``B`` directly.
60* If adding the dependency forms a cycle, e.g. ``B->C->A ~> B``. ``A``
61  is supposed to be at the lowest level while ``B`` is supposed to be at the
62  highest level. When you are developing ``C_test`` testing ``C``, your link may
63  fail surprisingly with ``undefined symbol`` if there is somehow a dependency on
64  some components of ``B``. You could fix the issue by adding the missing
65  dependency (``B``), however, then every test (``A_test``, ``B_test``,
66  ``C_test``) will link against every library. This breaks the motivation
67  of splitting ``B``, ``C`` and ``A`` into separate libraries and makes binaries
68  unnecessarily large. Moreover, the layering violation makes lower-level
69  libraries (e.g. ``A``) vulnerable to changes to higher-level libraries (e.g.
70  ``B``, ``C``).
71
72Resolution:
73
74* Add a dependency from ``A`` to ``B``.
75* The reference may be unintended and can be removed.
76* The dependency may be intentionally omitted because there are multiple
77  libraries like ``B``.  Consider linking ``B`` with object semantics by
78  surrounding it with ``--whole-archive`` and ``--no-whole-archive``.
79* In the case of circular dependency, sometimes merging the libraries are the best.
80
81There are two cases like a library sandwich where GNU ld will select a
82different object.
83
84* ``A.a B A2.so``: ``A.a`` may be used as an interceptor (e.g. it provides some
85  optimized libc functions and ``A2`` is libc).  ``B`` does not need to know
86  about ``A.a``, and ``A.a`` may be pulled into the link by other part of the
87  program. For linker portability, consider ``--whole-archive`` and
88  ``--no-whole-archive``.
89
90* ``A.a B A2.a``: similar to the above case but ``--warn-backrefs`` does not
91  flag the problem, because ``A2.a`` may be a replicate of ``A.a``, which is
92  redundant but benign. In some cases ``A.a`` and ``B`` should be surrounded by
93  a pair of ``--start-group`` and ``--end-group``. This is especially common
94  among system libraries (e.g.  ``-lc __isnanl references -lm``, ``-lc
95  _IO_funlockfile references -lpthread``, ``-lc __gcc_personality_v0 references
96  -lgcc_eh``, and ``-lpthread _Unwind_GetCFA references -lunwind``).
97
98  In C++, this is likely an ODR violation. We probably need a dedicated option
99  for ODR detection.
100