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

[MaskRay]

Update date .Dd

[MaskRay]

Change a .Ar to .Fl

[ruiu]

Thank you for doing this.

docs/ld.lld.1

221 ↗

(On Diff #188355)

options -> option

222–224 ↗

(On Diff #188355)

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]

Apply ruiu's suggestion

[MaskRay]

Does this look good now?

[ruiu]

LGTM

lld/trunk/docs/ld.lld.1

 .\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 .\" See https://llvm.org/LICENSE.txt for license information.
 .\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 .\"
 .\" This man page documents only lld's ELF linking support, obtained originally
 .\" from FreeBSD.
-.Dd September 26, 2018
+.Dd February 26, 2019
 .Dt LD.LLD 1
 .Os
 .Sh NAME
 .Nm ld.lld
 .Nd ELF linker from the LLVM project
 .Sh SYNOPSIS
 .Nm ld.lld
 .Op Ar options

 .It Fl -help
 Print a help message.
 .It Fl -icf Ns = Ns Cm all
 Enable identical code folding.
 .It Fl -icf Ns = Ns Cm safe
 Enable safe identical code folding.
 .It Fl -icf Ns = Ns Cm none
 Disable identical code folding.
+.It Fl -ignore-data-address-equality
+Ignore address equality of data. C/C++ requires each data to have a unique
+address. This option allows lld to do unsafe optimization that breaks the
+requirement: create copies of read-only data or merge two or more read-only data
+that happen to have the same value.
+.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
 Set the base address to
 .Ar value .
 .It Fl -init Ns = Ns Ar symbol
 Specify an initializer function.
 .It Fl -keep-unique Ns = Ns Ar symbol
 Do not fold
 .Ar symbol

 .It Fl -no-dynamic-linker
 Inhibit output of an
 .Li .interp
 section.
 .It Fl -no-gc-sections
 Disable garbage collection of unused sections.
 .It Fl -no-gnu-unique
 Disable STB_GNU_UNIQUE symbol binding.
+.It Fl -no-merge-exidx-entries
+Disable merging .ARM.exidx entries.
 .It Fl -no-rosegment
 Do not put read-only non-executable sections in their own segment.
 .It Fl -no-threads
 Do not run the linker multi-threaded.
 .It Fl -no-undefined-version
 Report version scripts that refer undefined symbols.
 .It Fl -no-undefined
 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
 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.
 .It Fl -noinhibit-exec
 Retain the executable output file whenever it is still usable.
 .It Fl -nostdlib
 Only search directories specified on the command line.
 .It Fl o Ar path
 Write the output executable, library, or object to
 .Ar path .

 which produces output with no ELF header.
 .It Fl -omagic , Fl N
 Set the text and data sections to be readable and writable.
 .It Fl -opt-remarks-filename Ar file
 Write optimization remarks in YAML format to
 .Ar file .
 .It Fl -opt-remarks-with-hotness
 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
 Always generate position independent thunks.
-.It Fl -pie
+.It Fl -pie , Fl -pic-executable
 Create a position independent executable.
 .It Fl -print-gc-sections
 List removed unused sections.
 .It Fl -print-icf-sections
 List identical folded sections.
 .It Fl -print-map
 Print a link map to the standard output.
 .It Fl -push-state

 Trace references to
 .Ar symbol .
 .It Fl -undefined Ns = Ns Ar symbol , Fl u Ar symbol
 Force
 .Ar symbol
 to be an undefined symbol during linking.
 .It Fl -unresolved-symbols Ns = Ns Ar value
 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
 Display the version number and proceed with linking if object files are
 specified.
 .It Fl V , Fl -version
 Display the version number and exit.
 .It Fl -verbose
 Verbose mode.
 .It Fl -version-script Ns = Ns Ar file