This is an archive of the discontinued LLVM Phabricator instance.

Differential D43072

ld.lld.1: add IMPLEMENTATION NOTES section documenting lld's handling
ClosedPublic

Authored by emaste on Feb 8 2018, 7:16 AM.

Details

Reviewers
ruiu
• rafael
Commits
rG1136f3f0fdb0: Add IMPLEMENTATION NOTES describing lld's .a handling in the man page
rL324739: Add IMPLEMENTATION NOTES describing lld's .a handling in the man page
rLLD324739: Add IMPLEMENTATION NOTES describing lld's .a handling in the man page
Summary

Add a section based on NewLLD.html explaining lld's handling of archive files.

Diff Detail

Repository
rLLD LLVM Linker

Event Timeline

emaste created this revision.Feb 8 2018, 7:16 AM
emaste added a subscriber: llvm-commits.Feb 8 2018, 5:46 PM
ruiu accepted this revision.Feb 8 2018, 7:32 PM

LGTM

This revision is now accepted and ready to land.Feb 8 2018, 7:32 PM
Closed by commit rLLD324739: Add IMPLEMENTATION NOTES describing lld's .a handling in the man page (authored by emaste). · Explain WhyFeb 9 2018, 7:38 AM
This revision was automatically updated to reflect the committed changes.
Herald added a subscriber: arichardson. · View Herald TranscriptFeb 9 2018, 7:38 AM

Revision Contents

PathSize
docs/
43 lines

Diff 133618

docs/ld.lld.1

.\" This file is distributed under the University of Illinois Open Source .\" This file is distributed under the University of Illinois Open Source
.\" License. See LICENSE.TXT for details. .\" License. See LICENSE.TXT for details.
.\" .\"
.\" This man page documents only lld's ELF linking support, obtained originally .\" This man page documents only lld's ELF linking support, obtained originally
.\" from FreeBSD. .\" from FreeBSD.
.Dd February 7, 2018 .Dd February 9, 2018
.Dt LD.LLD 1 .Dt LD.LLD 1
.Os .Os
.Sh NAME .Sh NAME
.Nm ld.lld .Nm ld.lld
.Nd ELF linker from the LLVM project .Nd ELF linker from the LLVM project
.Sh SYNOPSIS .Sh SYNOPSIS
.Nm ld.lld .Nm ld.lld
.Op Ar options .Op Ar options
▲ Show 20 Lines • Show All 462 Lines • ▼ Show 20 Lines
Do not allow relocations against read-only segments. Do not allow relocations against read-only segments.
This is the default. This is the default.
.It Cm wxneeded .It Cm wxneeded
Create a Create a
.Dv PT_OPENBSD_WXNEEDED .Dv PT_OPENBSD_WXNEEDED
segment. segment.
.El .El
.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.