introduce basic lld man page

[emaste]

Summary

Briefly describe lld's options. By krion@, Arshan Khanifar, and me.

I'd like to have something in the tree as soon as possible; we can expand on it over time.

[emaste]

Rafael I'd be happy for this to go upstream as well after editing.

[emaste]

While reviewing I found that ld does not support --output=path. We may find more of these, and will submit all of them upstream at the end of this.

[emaste]

• add . at end of descriptions
• wrap
• expand -o output argument
• use .Fn for _exit function markup

[emaste]

• Connect to Makefile
• document -z text, -z notext
• use .Dv for tags

[bjk]

Probably a lot of these need not be addressed before commit (especially "what are the valid values?").

usr.bin/clang/lld/ld.lld.1

1

Needs a copyright statement.

(Please also remember to update .Dd when committing.)

4

.Sh arguments are usually ALL-CAPS

9

Perhaps "long-options" is better, since there are not really any single-character options being described herein.

26

Definitions of what? Symbols?

30

maybe "if symbols from those libraries are used during symbol resolution"?

33

"the DT_AUXILIARY"? ("the" on the previous line, of course).

46

(Here and two lines prior) "*a* build ID note"?

52

Is there a way to control what compression scheme is used? (What is the default?)

54

"common" as in shared across multiple units, or as in frequently used?

56

An alias requires both source and destination, right? What does the "value" argument look like so as to make that happen?

74

I think there is some markup to use for .eh_frame_hdr and PT_GNU_EH_FRAME -- the latter might be a .Dv, and the former might just have to be .Li.

76

Maybe "the output" or perhaps something even more specific ("the output object")?

78

I a little bit wonder if it's worth mentioning some of the more useful ones, e.g., RUNPATH.

81

--start-lib and --end-lib should probably be adjacent, alphabetization notwithstanding.

83

"The name of the symbol to be used as the entry point to the resulting executable."?

85

"The maximum number of errors to emit before stopping (a value of zero indicates that there is no limit)"?

93

(all?)

98

"the"

99

"specified value"

103

inputs as in command-line arguments, known as "objfile"s in the synopsis? Probably this could be more clear.

105

Crud, am I looking at an old diff; I could have sworn a change message went by about using .Fn for _exit.

109

".Li .gdb_index"?

113

I think "Print a usage message" is more conventional.

119

"set the base address to
.Ar value", while repetitive, is probably more consistent with manpage style.

124

.Fl -lto-newpm-passes, presumably

126

Is this a number or something else? (What are the valid values?)

130

I don't know whether "code generation" is less conventional in this usage.

134

Is "root name" a term of art? Also, "to use" is a bit unclear about "for what?".

138

Do we want to list possible values?

142

I think a word or two is missing here.

150

.Li .interp
?
"sections" plural?

160

Maybe, "Warn on version scripts that refer to undefined symbols"?

166

This one seems confusing to me. Is it, "Always allow the output file to be executable"?

176

No '=' before value? Alas, for want of consistent user interface...

202

does this interact with new-dtags?

205

"The supported values are
.Ar windows
and
.Ar posix"

207

Read a linker script from the path
.Ar value .

209

How do we know which section this applies to? (Also, missing "the".)

214

"to
.Ar value ."

216

"Specifies the rule used to sort sections when a linker script is used."
What are the valid values?

225

I think "Lay out" as two words is better, here.
Also, "the symbol file".

227

, used for locating system libraries
?

233

.Ar type
both times.
Probably also use .Li for the choices.

235

.Fl -section-start
.Li .bss

237

ditto

247

"the indicated symbols", maybe?

251

.Fl -section-start
.Li .text
etc.

253

I'm not sure what this does; is it
Force the symbol name
.Ar value
to be undefined during linking.
?

255

What are the valid options?

270

Maybe, "Force all members of a static library to be included in the output file"?

272

Maybe, "Use wrapper functions for the indicated symbols"?

284

Need another .El, right?
(mdoc -Tlint ought to warn about this.)

286

This could probably have more prose, like
"The target ABIs supported by
.Nm
are:"

[emaste]

Thanks for the extensive comments! I'll address the grammatical ones before commit. The "valid values" questions etc. probably require more research and will be in a followup.

usr.bin/clang/lld/ld.lld.1

9

There is at least -o and others will follow, so I think options is preferable.

33

Yes. These were inherited from lld's --help text; I'll fix them up here before commit (and in lld's help).

[emaste]

usr.bin/clang/lld/ld.lld.1

54

Maybe "COMMON" to hint that it's the ELF definition of common?

78

In fact I think the flag may only control DT_RPATH vs DT_RUNPATH, will expand the description after confirming.

83

Maybe "Set the entry point in the executable to .Ar symbol" ?

85

Or two sentences - the short form makes sense for the help but we can be more verbose.

105

It seems I accidentally reverted this change in the most recent upload :(

142

Perhaps "Always set DT_NEEDED" but an expanded description is warranted.

[emaste]

First round of cleanup from bjk

[emaste]

usr.bin/clang/lld/ld.lld.1

26

Looked up ld.bfd description: allows symbol to be defined multiple times, and uses first def'n. Normally an error.

30

Need to check exact details.

52

Need to investigate.

56

I think it's --defsym=symbol=expr and it's not really (or perhaps, not just) an alias, further investigation needed.

93

I suspect it's --exclude-libs library[,library...]. GNU ld.bfd documents it as a colon- or comma-separated list of library names.

[emaste]

usr.bin/clang/lld/ld.lld.1

130

"codegen" is conventional in tool chain developer circles, but is probably not so meaningful for linker users. We should probably just rewrite this.

134

I don't know that "root name" is a term of art; the implication is that it's the base name of the library without lib prefix or extension. And the use is to link against the library.

-l foo searches paths specified by -L for libfoo.so and libfoo.a.

138

We should. I don't have a list handy.

Also we should probably have a cmdline option in lld to report all of the emulations.

[arshankhanifar_gmail.com]

usr.bin/clang/lld/ld.lld.1

26

I added some explanation in my branch

52

I found the options and the default

[wblock]

head/usr.bin/clang/lld/ld.lld.1

39 ↗

(On Diff #37727)

Use the serial comma: s/archive/archive,/

50 ↗

(On Diff #37727)

s/The following/These/
("The following" is almost always used incorrectly.)

221 ↗

(On Diff #37727)

Use the serial comma: s/library/library,/

336 ↗

(On Diff #37727)

Don't need the comma after "number".