diff options
| author | Ed Maste <emaste@freebsd.org> | 2018-02-09 15:36:13 +0000 |
|---|---|---|
| committer | Ed Maste <emaste@freebsd.org> | 2018-02-09 15:36:13 +0000 |
| commit | 1136f3f0fdb08cf93b1cc7e3746172bf02706a3f (patch) | |
| tree | 32ff1f1681b89a3528ed8b3976d5e92ad7015bcf | |
| parent | 6955b192ab81edcfe47d5aa3dbf20f49d973694e (diff) | |
| download | bcm5719-llvm-1136f3f0fdb08cf93b1cc7e3746172bf02706a3f.tar.gz bcm5719-llvm-1136f3f0fdb08cf93b1cc7e3746172bf02706a3f.zip | |
Add IMPLEMENTATION NOTES describing lld's .a handling in the man page
This content is based on the description in NewLLD.rst.
Differential Revision: https://reviews.llvm.org/D43072
llvm-svn: 324739
| -rw-r--r-- | lld/docs/ld.lld.1 | 43 |
1 files changed, 42 insertions, 1 deletions
diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1 index 65ff684139c..32ff7dfa37a 100644 --- a/lld/docs/ld.lld.1 +++ b/lld/docs/ld.lld.1 @@ -3,7 +3,7 @@ .\" .\" This man page documents only lld's ELF linking support, obtained originally .\" from FreeBSD. -.Dd February 7, 2018 +.Dd February 9, 2018 .Dt LD.LLD 1 .Os .Sh NAME @@ -482,3 +482,44 @@ Create a segment. .El .El +.Sh IMPLEMENTATION NOTES +.Nm Ap s +handing of archive files (those with a +.Cm .a +file extension) is different from traditional linkers used on Unix-like +systems. +.Pp +Traditional linkers maintain a set of undefined symbols during linking. +The linker processes each file in the order in which it appears on the +command line, until the set of undefined symbols becomes empty. +An object file is linked into the output object when it is encountered, +with its undefined symbols added to the set. +Upon encountering an archive file a traditional linker searches the objects +contained therein, and processes those that satisfy symbols in the unresolved +set. +.Pp +Handling mutually dependent archives may be awkward when using a traditional +linker. +Archive files may have to be specified multiple times, or the special command +line options +.Fl -start-group +and +.Fl -end-group +may be used to have the linker loop over the files in the group until no new +symbols are added to the set. +.Pp +.Nm +records all symbols found in objects and archives as it iterates over +command line arguments. +When +.Nm +encounters an undefined symbol that can be resolved by an object file +contained in a previously processed archive file, it immediately extracts +and links it into the output object. +.Pp +With certain archive inputs +.Nm +may produce different results compared to traditional linkers. +In practice, large bodies of third party software have been linked with +.Nm +without material issues. |
