This is an archive of the discontinued LLVM Phabricator instance.

Differential D58669

[ELF] Explain some options in ld.lld.1
ClosedPublic

Authored by MaskRay on Feb 26 2019, 5:43 AM.

Details

Reviewers
ruiu
grimar
Commits
rG7507208a9adf: [ELF] Explain some options in ld.lld.1
rLLD355173: [ELF] Explain some options in ld.lld.1
rL355173: [ELF] Explain some options in ld.lld.1

Diff Detail

Event Timeline

MaskRay created this revision.Feb 26 2019, 5:43 AM
Herald added a project: Restricted Project. · View Herald TranscriptFeb 26 2019, 5:43 AM
Herald added subscribers: llvm-commits, jdoerfert, srhines. · View Herald Transcript
Harbormaster completed remote builds in B28544: Diff 188353.Feb 26 2019, 5:45 AM
MaskRay updated this revision to Diff 188354.Feb 26 2019, 5:47 AM

Update date .Dd

Harbormaster completed remote builds in B28545: Diff 188354.Feb 26 2019, 5:48 AM
MaskRay updated this revision to Diff 188355.Feb 26 2019, 5:50 AM

Change a .Ar to .Fl

Harbormaster completed remote builds in B28546: Diff 188355.Feb 26 2019, 5:50 AM
ruiu added a comment.Feb 26 2019, 11:07 AM

Thank you for doing this.

docs/ld.lld.1
221

options -> option

222–224

I'd think this is hard to understand for those who are just reading this manual page. We don't explain anything about .llvm_addrsig for example.

Maybe it's better to explain it at a high level first? For example: C/C++ requires each data has a unique address. This option allows lld do unsafe optimization that breaks the requirement. If this option is given, lld may create copies of read-only data or merge two or more read-only data that happen to have the same value.

MaskRay updated this revision to Diff 188484.Feb 26 2019, 5:14 PM

Apply ruiu's suggestion

Harbormaster completed remote builds in B28578: Diff 188484.Feb 26 2019, 5:14 PM
MaskRay added a comment.Feb 28 2019, 5:11 PM

Does this look good now?

ruiu accepted this revision.Feb 28 2019, 7:41 PM

LGTM

This revision is now accepted and ready to land.Feb 28 2019, 7:41 PM
Closed by commit rL355173: [ELF] Explain some options in ld.lld.1 (authored by MaskRay). · Explain WhyFeb 28 2019, 8:49 PM
This revision was automatically updated to reflect the committed changes.

Revision Contents

PathSize
docs/
61 lines

Diff 188353

docs/ld.lld.1

Show First 20 Lines • Show All 211 Lines • ▼ Show 20 Lines
.It Fl -help .It Fl -help
Print a help message. Print a help message.
.It Fl -icf Ns = Ns Cm all .It Fl -icf Ns = Ns Cm all
Enable identical code folding. Enable identical code folding.
.It Fl -icf Ns = Ns Cm safe .It Fl -icf Ns = Ns Cm safe
Enable safe identical code folding. Enable safe identical code folding.
.It Fl -icf Ns = Ns Cm none .It Fl -icf Ns = Ns Cm none
Disable identical code folding. Disable identical code folding.
.It Fl -ignore-data-address-equality
Ignore address equality of data. This options allows copy relocation for object
ruiuUnsubmitted
Not Done
ReplyInline Actions

options -> option

ruiu: options -> option
symbols with non-default visibility. When used together with
.Ar -icf=all ,
both .dynsym and .llvm_addrsig are ignored for ICF.
ruiuUnsubmitted
Not Done
ReplyInline Actions

I'd think this is hard to understand for those who are just reading this manual page. We don't explain anything about .llvm_addrsig for example.

Maybe it's better to explain it at a high level first? For example: C/C++ requires each data has a unique address. This option allows lld do unsafe optimization that breaks the requirement. If this option is given, lld may create copies of read-only data or merge two or more read-only data that happen to have the same value.

ruiu: I'd think this is hard to understand for those who are just reading this manual page. We don't…
.It Fl -ignore-function-address-equality
Ignore address equality of functions. This option allows non-PIC calls to a
function with non-default visibility in a shared object. The function may have
different addresses within the executable and within the shared object.
.It Fl -image-base Ns = Ns Ar value .It Fl -image-base Ns = Ns Ar value
Set the base address to Set the base address to
.Ar value . .Ar value .
.It Fl -init Ns = Ns Ar symbol .It Fl -init Ns = Ns Ar symbol
Specify an initializer function. Specify an initializer function.
.It Fl -keep-unique Ns = Ns Ar symbol .It Fl -keep-unique Ns = Ns Ar symbol
Do not fold Do not fold
.Ar symbol .Ar symbol
Show All 33 Lines
.It Fl -no-dynamic-linker .It Fl -no-dynamic-linker
Inhibit output of an Inhibit output of an
.Li .interp .Li .interp
section. section.
.It Fl -no-gc-sections .It Fl -no-gc-sections
Disable garbage collection of unused sections. Disable garbage collection of unused sections.
.It Fl -no-gnu-unique .It Fl -no-gnu-unique
Disable STB_GNU_UNIQUE symbol binding. Disable STB_GNU_UNIQUE symbol binding.
.It Fl -no-merge-exidx-entries
Disable merging .ARM.exidx entries.
.It Fl -no-rosegment .It Fl -no-rosegment
Do not put read-only non-executable sections in their own segment. Do not put read-only non-executable sections in their own segment.
.It Fl -no-threads .It Fl -no-threads
Do not run the linker multi-threaded. Do not run the linker multi-threaded.
.It Fl -no-undefined-version .It Fl -no-undefined-version
Report version scripts that refer undefined symbols. Report version scripts that refer undefined symbols.
.It Fl -no-undefined .It Fl -no-undefined
Report unresolved symbols even if the linker is creating a shared library. Report unresolved symbols even if the linker is creating a shared library.
.It Fl -no-warn-symbol-ordering
Do not warn about problems with the symbol ordering file or call graph profile.
.It Fl -no-whole-archive .It Fl -no-whole-archive
Restores the default behavior of loading archive members. Restores the default behavior of loading archive members.
.It Fl -no-pie .It Fl -no-pie , Fl -no-pic-executable
Do not create a position independent executable. Do not create a position independent executable.
.It Fl -noinhibit-exec .It Fl -noinhibit-exec
Retain the executable output file whenever it is still usable. Retain the executable output file whenever it is still usable.
.It Fl -nostdlib .It Fl -nostdlib
Only search directories specified on the command line. Only search directories specified on the command line.
.It Fl o Ar path .It Fl o Ar path
Write the output executable, library, or object to Write the output executable, library, or object to
.Ar path . .Ar path .
Show All 25 Lines
which produces output with no ELF header. which produces output with no ELF header.
.It Fl -omagic , Fl N .It Fl -omagic , Fl N
Set the text and data sections to be readable and writable. Set the text and data sections to be readable and writable.
.It Fl -opt-remarks-filename Ar file .It Fl -opt-remarks-filename Ar file
Write optimization remarks in YAML format to Write optimization remarks in YAML format to
.Ar file . .Ar file .
.It Fl -opt-remarks-with-hotness .It Fl -opt-remarks-with-hotness
Include hotness information in the optimization remarks file. Include hotness information in the optimization remarks file.
.It Fl -orphan-handling Ns = Ns Ar mode
Control how orphan sections are handled. An orphan section is one not
specifically mentioned in a linker script.
.Ar mode
may be:
.Pp
.Bl -tag -width 2n -compact
.It Cm place
Place orphan sections in suitable output sections.
.It Cm warn
Place orphan sections as for
.Cm place
and also report a warning.
.It Cm error
Place orphan sections as for
.Cm place
and also report an error.
.El
.Pp
.Cm place
is the default.
.It Fl -pack-dyn-relocs Ns = Ns Ar format
Pack dynamic relocations in the given format.
.Ar format
may be:
.Pp
.Bl -tag -width 2n -compact
.It Cm none
Don't pack. Dynamic relocations are encoded in SHT_REL(A).
.It Cm android
Pack dynamic relocations in SHT_ANDROID_REL(A).
.It Cm relr
Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_REL(A).
.It Cm android+relr
Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_ANDROID_REL(A).
.El
.Pp
.Cm none
is the default. If
.Fl -use-android-relr-tags
is specified, use SHT_ANDROID_RELR instead of SHT_RELR.
.Pp
.It Fl -pic-veneer .It Fl -pic-veneer
Always generate position independent thunks. Always generate position independent thunks.
.It Fl -pie .It Fl -pie , Fl -pic-executable
Create a position independent executable. Create a position independent executable.
.It Fl -print-gc-sections .It Fl -print-gc-sections
List removed unused sections. List removed unused sections.
.It Fl -print-icf-sections .It Fl -print-icf-sections
List identical folded sections. List identical folded sections.
.It Fl -print-map .It Fl -print-map
Print a link map to the standard output. Print a link map to the standard output.
.It Fl -push-state .It Fl -push-state
▲ Show 20 Lines • Show All 102 Lines • ▼ Show 20 Lines
Trace references to Trace references to
.Ar symbol . .Ar symbol .
.It Fl -undefined Ns = Ns Ar symbol , Fl u Ar symbol .It Fl -undefined Ns = Ns Ar symbol , Fl u Ar symbol
Force Force
.Ar symbol .Ar symbol
to be an undefined symbol during linking. to be an undefined symbol during linking.
.It Fl -unresolved-symbols Ns = Ns Ar value .It Fl -unresolved-symbols Ns = Ns Ar value
Determine how to handle unresolved symbols. Determine how to handle unresolved symbols.
.It Fl -use-android-relr-tags
Use SHT_ANDROID_RELR / DT_ANDROID_RELR* tags instead of SHT_RELR / DT_RELR*.
.It Fl v .It Fl v
Display the version number and proceed with linking if object files are Display the version number and proceed with linking if object files are
specified. specified.
.It Fl V , Fl -version .It Fl V , Fl -version
Display the version number and exit. Display the version number and exit.
.It Fl -verbose .It Fl -verbose
Verbose mode. Verbose mode.
.It Fl -version-script Ns = Ns Ar file .It Fl -version-script Ns = Ns Ar file
▲ Show 20 Lines • Show All 166 Lines • Show Last 20 Lines