[PATCH] D86762: [ELF] Add documentation for --warn-backrefs: a layering check tool

[Peter Smith via Phabricator via llvm-commits]

psmith added a comment.

I've put some comments, mostly concentrating on the early part. I've not had a chance to go through the examples at the bottom in detail. I can't spot anything obviously wrong though.



================
Comment at: lld/docs/ELF/warn_backrefs.rst:4
+
+Linkers process input files from left to right and maintain the current set of
+undefined symbols. If an archive member (or an object file surrounded by
----------------
I think it would be better to separate out LLD's library search order from BFD as this information would be useful independently of --warn-backrefs.

We could also start with a very quick summary:

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

For this section (apologies for the rewrite) I suggest something like:

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 a library or an object file surrounded by ``--start-lib`` and ``--end-lib`` that library 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 library 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 library cannot have an undefined symbol resolved by a library 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 between libraries the libraries 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 library can be placed on the command line.

LLD remembers the symbol table of libraries that it has previously seen, so if there is a reference from an Input file to the right of a library, LLD will still search that library for a resolving definition for any undefined references. This means that a library 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 library 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 libraries that both define the same symbols.

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



================
Comment at: lld/docs/ELF/warn_backrefs.rst:16
+
+``--warn-backrefs`` can identify such an invocation which may be incompatible
+with GNU ld:
----------------
can identify an invocation that may be incompatible with GNU ld:


================
Comment at: lld/docs/ELF/warn_backrefs.rst:27
+
+The single pass linker such as GNU ld actually has a nice property: it is a
+layering check tool which enforces a topological order of libraries.
----------------
The ``--warn-backrefs`` option can also provide a check to enforce a topological order of libraries, which can be useful to detect layering violations.


================
Comment at: lld/docs/ELF/warn_backrefs.rst:48
+  ``C_test``) will link against every library. This breaks the motivation
+  breaking ``B``, ``C`` and ``A`` into separate libraries and makes binaries
+  unnecessarily large.  Moreover, the layering violation makes lower-level
----------------
This breaks the motivation of splitting ``B``, ``C`` and ``A`` into separate libraries


================
Comment at: lld/docs/ELF/warn_backrefs.rst:66
+
+There is a variant of ``A.a B A2.so``: ``A.a B A2.a``. I name this a "linking
+sandwich problem".
----------------
Although not important, it may be worth avoiding the first person "I" in documentation. 

Perhaps. "There is a variant of the (Rare) ``A.a B A2.so`` case that looks like a library sandwich.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D86762/new/

https://reviews.llvm.org/D86762