[ELF] Add missing options to ld.lld.1

[MaskRay]

Add more options

[ruiu]

ELF/Options.td

61 ↗

(On Diff #157769)

Add "(default") to this line just like we do for other default options.

docs/ld.lld.1

43

Is the vertical bar the right notation? Please mimic other options that have aliases.

[MaskRay]

• "Do not apply link-time values for dynamic relocations">;

+ "Do not apply link-time values for dynamic relocations (default)">;

[MaskRay]

docs/ld.lld.1

43

Ideally, a newline will be the best (which is also used in ld.bfd.1)

But I don't know how to express that in groff_mdoc. A vertical bar compared with a comma is more clear here. --version, -v is the only example I find and I have updated it.

[ruiu]

Ed might know how to format options with aliases.

[pcc]

docs/ld.lld.1

43

The only way that I can see to do it is like this:

diff --git a/lld/docs/ld.lld.1 b/lld/docs/ld.lld.1
index c9662856b89..d44995c842d 100644
--- a/lld/docs/ld.lld.1
+++ b/lld/docs/ld.lld.1
@@ -26,19 +26,24 @@ It accepts most of the same command line arguments and linker scripts
 as GNU linkers.
 .Pp
 These options are available:
-.Bl -tag -width indent
+.Bl -tag -width indent -compact
+.Pp
 .It Fl -allow-multiple-definition
 Do not error if a symbol is defined multiple times.
 The first definition will be used.
+.Pp
 .It Fl -as-needed
 Only set
 .Dv DT_NEEDED
 for shared libraries if used.
+.Pp
 .It Fl -auxiliary Ns = Ns Ar value
 Set the
 .Dv DT_AUXILIARY
 field to the specified name.
+.Pp
 .It Fl -Bdynamic
+.It Fl -dy
 Link against shared libraries.
 .It Fl -Bstatic
 Do not link against shared libraries.

[MaskRay]

Use -compact and add .Pp

[MaskRay]

There should be no | now.

[MaskRay]

Prefer --defsym f=1 to --defsym=f=1

[emaste]

For reference I had a discussion on markup for option aliases with Ingo Schwarze and he wrote:

The standard method for achieving similar output as in the GNU ld(1) manual page goes as follows (without the comments i'm inserting/appending, of course):

The options are as follows:
.Pp \" You need this if you use -compact on the next line.
.Bl -tag -width Ds -compact
.It Fl l Ar libName
.\" No paragraph break here.
.It Fl -library Ns = Ns Ar libName
Add archive file ...
.Pp \" You need this between items if you use -compact above.
.It Fl L Ar searchdir
.It Fl -library-path Ns = Ns Ar searchdir
Add path ...
.El
.Pp \" You always need this if some text follows, even without -compact.

Then again, if the the options all fit on one output line, i don't really see the need and would rather recommend simply:

The options are as follows:
.Bl -tag -width Ds
.It Fl l Ar libName , Fl -library Ns = Ns Ar libName
Add archive file ...
.It Fl L Ar searchdir , Fl -library-path Ns = Ns Ar searchdir
Add path ...
.El
.Pp

If you do this, always put the short option left of the long one, and decide alphabetic ordering by the short one, not by the long one.

[emaste]

docs/ld.lld.1

6

Bump .Dd upon commit

52

What is the reason for changing these from Ns = Ns? According to Ingo that's what the markup should be.

[emaste]

FWIW I don't have a strong opinion on | vs newline to separate aliases, but if we are going to go with the newline -compact and .Pp approach I'd suggest making that change as a separate commit first so that the actual content changes here are easier to see/review.

[MaskRay]

Remove -compact and .Pp , put aliasing options on the same line

[MaskRay]

FWIW I don't have a strong opinion on | vs newline to separate aliases, but if we are going to go with the newline -compact and .Pp approach I'd suggest making that change as a separate commit first so that the actual content changes here are easier to see/review.

Done

If you do this, always put the short option left of the long one, and decide alphabetic ordering by the short one, not by the long one.

I agree with this rule generally for other software but... for linker options (with a lot of short and long options for various historical heritage, single/double dashes...) I still have the tendency not to prefer unusual short options, e.g. -h is a rather uncommon alias of -soname
Similarly, I want to put --strip-debug before -S. --discard-all before -x.

[MaskRay]

Update

[MaskRay]

Commit uncontroversial parts

[MaskRay]

.

[MaskRay]

Minor style change to --omagic

[ruiu]

docs/ld.lld.1

39

Why did you remove "="?

413

Why did you swap the order?

[MaskRay]

docs/ld.lld.1

39

https://github.com/freebsd/freebsd/blob/4b26291ed887f8245f4c355f224743bfde7120f7/usr.bin/clang/lld/ld.lld.1#L70 uses this form but there are also other places preferring option=bar.

If you think = is better than a space, I can change all of them (Eq options) to use =.

413

The long option --version is used as the key here for alphabetical sorting. --version should be ordered before --version-script so their orders are swapped.

[ruiu]

docs/ld.lld.1

39

The GNU's convention seems to always add = for long options that take arguments. I'd follow that convention, but can you leave them alone for now?

I think you changed too many things in a single patch. Can you do that step by step? I'd revert all but the change to add missing options.

[MaskRay]

Remove changes replacing = with

[MaskRay]

.

[ruiu]

docs/ld.lld.1

390–392

Please also revert all these line-moving changes.

[MaskRay]

Remove line moving changes

[ruiu]

docs/ld.lld.1

234

Don't remove these options from the manual.

[MaskRay]

Add back --no-pie --enable-new-dtags --no-gc-sections

[ruiu]

docs/ld.lld.1

205

This should be

Do not fold
.Ar symbol
during ICF.

[MaskRay]

Use .Ar in --keep-unique

[ruiu]

docs/ld.lld.1

219–220

Consistently add = between a long option and its argument.

[MaskRay]

--library-path dir => --library-path=dir

[ruiu]

docs/ld.lld.1

205

This is redundant. We don't say "this value" for other options that takes a "value", for example.

[MaskRay]

Remove redundant "this"

[ruiu]

LGTM

Please create a small patch like this one next time for ease of code review. Thanks!

docs/ld.lld.1

 .\" This file is distributed under the University of Illinois Open Source
 .\" License. See LICENSE.TXT for details.
 .\"
 .\" This man page documents only lld's ELF linking support, obtained originally
 .\" from FreeBSD.
 .Dd April 28, 2018
 .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

 Do not error if a symbol is defined multiple times.
 The first definition will be used.
 .It Fl -apply-dynamic-relocs
 Apply link-time values for dynamic relocations.
 .It Fl -as-needed
 Only set
 .Dv DT_NEEDED
 for shared libraries if used.
-.It Fl -auxiliary Ns = Ns Ar value
+.It Fl -auxiliary Ar value
 Set the
 .Dv DT_AUXILIARY
 field to the specified name.
-.It Fl -Bdynamic
+.It Fl -Bdynamic , Fl -dy
 Link against shared libraries.
-.It Fl -Bstatic
+.It Fl -Bstatic , Fl -static , Fl -dn
 Do not link against shared libraries.
 .It Fl -Bsymbolic
 Bind defined symbols locally.
 .It Fl -Bsymbolic-functions
 Bind defined function symbols locally.
 .It Fl -build-id Ns = Ns Ar value
 Generate a build ID note.
 .Ar value
 may be one of
 .Cm fast ,
 .Cm md5 ,
 .Cm sha1 ,
 .Cm tree ,
 .Cm uuid ,
 .Cm 0x Ns Ar hex-string ,
 and
 .Cm none .
 .Cm tree
 is an alias for
 .Cm sha1 .
 Build-IDs of type
 .Cm fast ,
 .Cm md5 ,
 .Cm sha1 ,
 and
 .Cm tree
 are calculated from the object contents.
 .Cm fast
 is not intended to be cryptographically secure.
 .It Fl -build-id
 Synonym for
-.Fl -build-id Ns = Ns Cm fast .
+.Fl -build-id= Ns Cm fast .
 .It Fl -color-diagnostics Ns = Ns Ar value
 Use colors in diagnostics.
 .Ar value
 may be one of
 .Cm always ,
 .Cm auto ,
 and
 .Cm never .
 .Cm auto
 enables color if and only if output is to a terminal.
 .It Fl -color-diagnostics
 Alias for
-.Fl -color-diagnostics Ns = Ns Cm auto .
-.It Fl -compress-debug-sections Ns = Ns Ar value
+.Fl -color-diagnostics= Ns Cm auto .
+.It Fl -compress-debug-sections Ar value
 Compress DWARF debug sections.
 .Ar value
 may be
 .Cm none
 or
 .Cm zlib .
+.It Fl -cref
+Output cross reference table.
 .It Fl -define-common
+.It Fl d
 Assign space to common symbols.
-.It Fl -defsym Ns = Ns Ar symbol Ns = Ns Ar expression
+.It Fl -defsym Ar symbol Ns = Ns Ar expression
 Define a symbol alias.
 .Ar expression
 may be another symbol or a linker script expression.
 For example,
-.Ql --defsym=foo=bar
+.Fl -defsym Cm foo= Ns Cm bar
 or
-.Ql --defsym=foo=bar+0x100 .
+.Fl -defsym Cm foo= Ns Cm bar+0x100 .
 .It Fl -demangle
 Demangle symbol names.
 .It Fl -disable-new-dtags
 Disable new dynamic tags.
-.It Fl -discard-all
+.It Fl -discard-all , Fl x
 Delete all local symbols.
-.It Fl -discard-locals
+.It Fl -discard-locals , Fl X
 Delete temporary local symbols.
 .It Fl -discard-none
 Keep all symbols in the symbol table.
-.It Fl -dynamic-linker Ns = Ns Ar value
+.It Fl -dynamic-linker Ar value
 Specify the dynamic linker to be used for a dynamically linked executable.
 This is recorded in an ELF segment of type
 .Dv PT_INTERP .
-.It Fl -dynamic-list Ns = Ns Ar file
+.It Fl -dynamic-list Ar file
 Read a list of dynamic symbols from
 .Ar file .
 .It Fl -eh-frame-hdr
 Request creation of
 .Li .eh_frame_hdr
 section and
 .Dv PT_GNU_EH_FRAME
 segment header.
 .It Fl -emit-relocs
+.It Fl q
 Generate relocations in the output.
-.It Fl -enable-new-dtags
-Enable new dynamic tags.
 .It Fl -end-lib
 End a grouping of objects that should be treated as if they were together
 in an archive.
-.It Fl -entry Ns = Ns Ar entry
+.It Fl -entry Ar entry
 Name of entry point symbol.
-.It Fl -error-limit Ns = Ns Ar value
+.It Fl -error-limit Ar value
 Maximum number of errors to emit before stopping.
 A value of zero indicates that there is no limit.
 .It Fl -error-unresolved-symbols
 Report unresolved symbols as errors.
-.It Fl -exclude-libs Ns = Ns Ar value
+.It Fl -exclude-libs Ar value
 Exclude static libraries from automatic export.
-.It Fl -export-dynamic-symbol Ns = Ns Ar symbol
+.It Fl -export-dynamic-symbol Ar symbol
 Include
 .Ar symbol
 in the dynamic symbol table.
 .It Fl -export-dynamic
+.It Fl E
 Put symbols in the dynamic symbol table.
 .It Fl -fatal-warnings
 Treat warnings as errors.
-.It Fl -filter Ns = Ns Ar value
+.It Fl -filter Ar value , Fl F Ar value
 Set the
 .Dv DT_FILTER
 field to the specified value.
-.It Fl -fini Ns = Ns Ar symbol
+.It Fl -fini Ar symbol
 Specify a finalizer function.
-.It Fl -format Ns = Ns Ar input-format
+.It Fl -format Ar input-format , Fl b Ar input-format
 Specify the format of the inputs following this option.
 .Ar input-format
 may be one of
 .Cm binary ,
 .Cm elf ,
 and
 .Cm default .
 .Cm default
 is a synonym for
 .Cm elf .
 .It Fl -gc-sections
 Enable garbage collection of unused sections.
 .It Fl -gdb-index
 Generate
 .Li .gdb_index
 section.
-.It Fl -hash-style Ns = Ns Ar value
+.It Fl -hash-style Ar value
 Specify hash style.
 .Ar value
 may be
 .Cm sysv ,
 .Cm gnu ,
 or
 .Cm both .
 .Cm both
 is the default.
 .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 -image-base Ns = Ns Ar value
+.It Fl -icf Ns = Ns Cm safe
+Enable safe identical code folding.
+.It Fl -image-base Ar value
 Set the base address to
 .Ar value .
-.It Fl -init Ns = Ns Ar symbol
+.It Fl -init Ar symbol
 Specify an initializer function.
+.It Fl -keep-unique Ar symbol
+Do not fold this symbol during ICF.
+.It Fl L Ar dir , Fl -library-path Ar dir
+Add a directory to the library search path.
+.It Fl l Ar libName, Fl -library Ar libName
+Root name of library to use.
 .It Fl -lto-aa-pipeline Ns = Ns Ar value
 AA pipeline to run during LTO.
 Used in conjunction with
 .Fl -lto-newpm-passes .
 .It Fl -lto-newpm-passes Ns = Ns Ar value
 Passes to run during LTO.
 .It Fl -lto-O Ns Ar opt-level
 Optimization level for LTO.
 .It Fl -lto-partitions Ns = Ns Ar value
 Number of LTO codegen partitions.
-.It Fl L Ar dir
-Add a directory to the library search path.
-.It Fl l Ar libName
-Root name of library to use.
-.It Fl -Map Ns = Ns Ar file
+.It Fl -Map Ar file , Fl M Ar file
 Print a link map to
 .Ar file .
 .It Fl m Ar value
 Set target emulation.
 .It Fl -no-as-needed
 Always set
 .Dv DT_NEEDED
 for shared libraries.
 .It Fl -no-color-diagnostics
 Do not use colors in diagnostics.
 .It Fl -no-define-common
 Do not assign space to common symbols.
 .It Fl -no-demangle
 Do not demangle symbol names.
 .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-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-whole-archive
 Restores the default behavior of loading archive members.
 .It Fl -noinhibit-exec
 Retain the executable output file whenever it is still usable.
-.It Fl -no-pie
-Do not create a position independent executable.
 .It Fl -nostdlib
 Only search directories specified on the command line.
-.It Fl -oformat Ns = Ns Ar format
+.It Fl -oformat Ar format
 Specify the format for the output object file.
 The only supported
 .Ar format
 is
 .Cm binary ,
 which produces output with no ELF header.
 .It Fl -omagic
+.It 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 O Ns Ar value
 Optimize output file size.
 .Ar value
 may be:
-.Pp
 .Bl -tag -width 2n -compact
 .It Cm 0
 Disable string merging.
 .It Cm 1
 Enable string merging.
 .It Cm 2
 Enable string tail merging.
 .El
-.Pp
 .Fl O Ns Cm 1
 is the default.
 .It Fl o Ar path
 Write the output executable, library, or object to
 .Ar path .
 If not specified,
 .Dv a.out
 is used as a default.
 .It Fl -pie
 Create a position independent executable.
 .It Fl -print-gc-sections
 List removed unused sections.
 .It Fl -print-map
 Print a link map to the standard output.
 .It Fl -push-state
 Save the current state of
 .Fl -as-needed ,
 .Fl -static ,
 and
 .Fl -while-archive.
 .It Fl -pop-state
 Undo the effect of
 .Fl -push-state.
-.It Fl -relocatable
+.It Fl -relocatable , Fl r
 Create relocatable object file.
-.It Fl -reproduce Ns = Ns Ar value
+.It Fl -reproduce Ar value
 Dump linker invocation and input files for debugging.
-.It Fl -retain-symbols-file Ns = Ns Ar file
+.It Fl -retain-symbols-file Ar file
 Retain only the symbols listed in the file.
-.It Fl -rpath Ns = Ns Ar value
+.It Fl -rpath Ar value , Fl R Ar value
 Add a
 .Dv DT_RUNPATH
 to the output.
-.It Fl -rsp-quoting Ns = Ns Ar value
+.It Fl -rsp-quoting Ar value
 Quoting style for response files.
 The supported values are
 .Cm windows
 and
 .Cm posix .
-.It Fl -script Ns = Ns Ar file
+.It Fl -script Ar file , Fl T Ar file
 Read linker script from
 .Ar file .
-.It Fl -section-start Ns = Ar section Ns = Ns Ar address
+.It Fl -section-start Ar section Ns = Ns Ar address
 Set address of section.
-.It Fl -shared
+.It Fl -shared , Fl -Bsharable
 Build a shared object.
-.It Fl -soname Ns = Ns Ar value
+.It Fl -soname Ar value , Fl h Ar value
 Set
 .Dv DT_SONAME
 to
 .Ar value .
-.It Fl -sort-section Ns = Ns Ar value
+.It Fl -sort-section Ar value
 Specifies sections sorting rule when linkerscript is used.
 .It Fl -start-lib
 Start a grouping of objects that should be treated as if they were together
 in an archive.
-.It Fl -strip-all
+.It Fl -strip-all , Fl s
 Strip all symbols.
-.It Fl -strip-debug
+.It Fl -strip-debug , Fl S
 Strip debugging information.
-.It Fl -symbol-ordering-file Ns = Ns Ar file
+.It Fl -symbol-ordering-file Ar file
 Lay out sections in the order specified by
 .Ar file .
-.It Fl -sysroot Ns = Ns Ar value
+.It Fl -sysroot Ar value
 Set the system root.
 .It Fl -target1-abs
 Interpret
 .Dv R_ARM_TARGET1
 as
 .Dv R_ARM_ABS32 .
 .It Fl -target1-rel
 Interpret
 .Dv R_ARM_TARGET1
 as
 .Dv R_ARM_REL32 .
-.It Fl -target2 Ns = Ns Ar type
+.It Fl -target2 Ar type
 Interpret
 .Dv R_ARM_TARGET2
 as
 .Ar type ,
 where
 .Ar type
 is one of
 .Cm rel ,
 .Cm abs ,
 or
 .Cm got-rel .
-.It Fl -Tbss Ns = Ns Ar value
+.It Fl -Tbss Ar value
 Same as
 .Fl -section-start
 with
 .Li .bss
 as the sectionname.
-.It Fl -Tdata Ns = Ns Ar value
+.It Fl -Tdata Ar value
 Same as
 .Fl -section-start
 with
 .Li .data
 as the sectionname.
 .It Fl -thinlto-cache-dir Ns = Ns Ar value
 Path to ThinLTO cached object file directory.
-.It Fl -thinlto-cache-policy Ns = Ns Ar value
+.It Fl -thinlto-cache-policy Ar value
 Pruning policy for the ThinLTO cache.
 .It Fl -thinlto-jobs Ns = Ns Ar value
 Number of ThinLTO jobs.
 .It Fl -threads
 Run the linker multi-threaded.
 This option is enabled by default.
-.It Fl -trace-symbol Ns = Ns Ar symbol
-Trace references to
-.Ar symbol .
 .It Fl -trace
 Print the names of the input files.
-.It Fl -Ttext Ns = Ns Ar value
+.It Fl -trace-symbol Ar symbol , Fl y Ar symbol
+Trace references to
+.Ar symbol .
+.It Fl -Ttext Ar value
 Same as
 .Fl -section-start
 with
 .Li .text
 as the sectionname.
-.It Fl -undefined Ns = Ns Ar symbol
+.It Fl -undefined Ar symbol
+.It Fl u Ar symbol
 Force
 .Ar symbol
 to be an undefined symbol during linking.
-.It Fl -unresolved-symbols Ns = Ns Ar value
+.It Fl -unresolved-symbols Ar value
 Determine how to handle unresolved symbols.
+.It Fl v
+Display the version number and proceed with linking if object files are
+specified.
 .It Fl -verbose
 Verbose mode.
-.It Fl -version-script Ns = Ns Ar file
+.It Fl -version , Fl V
+Display the version number and exit.
+.It Fl -version-script Ar file
 Read version script from
 .Ar file .
-.It Fl V , Fl -version
-Display the version number and exit.
-.It Fl v
-Display the version number and proceed with linking if object files are
-specified.
 .It Fl -warn-backrefs
 Warn about reverse or cyclic dependencies to or between static archives.
 This can be used to ensure linker invocation remains compatible with
 traditional Unix-like linkers.
 .It Fl -warn-common
 Warn about duplicate common symbols.
 .It Fl -warn-unresolved-symbols
 Report unresolved symbols as warnings.
 .It Fl -whole-archive
 Force load of all members in a static library.
-.It Fl -wrap Ns = Ns Ar symbol
+.It Fl -wrap Ar symbol
 Use wrapper functions for symbol.
 .It Fl z Ar option
 Linker option extensions.
 .Bl -tag -width indent
 .It Cm execstack
 Make the main stack executable.
 Stack permissions are recorded in the
 .Dv PT_GNU_STACK