Page MenuHomeFreeBSD

introduce basic lld man page

Authored by emaste on Jan 9 2018, 4:49 PM.


Group Reviewers
rS327770: lld: introduce basic man page

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.

Diff Detail

rS FreeBSD src repository - subversion
Automatic diff as part of commit; lint not applicable.
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

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

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.

  • add . at end of descriptions
  • wrap
  • expand -o output argument
  • use .Fn for _exit function markup
  • Connect to Makefile
  • document -z text, -z notext
  • use .Dv for tags

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

1 ↗(On Diff #37707)

Needs a copyright statement.

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

4 ↗(On Diff #37707)

.Sh arguments are usually ALL-CAPS

9 ↗(On Diff #37707)

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

26 ↗(On Diff #37707)

Definitions of what? Symbols?

30 ↗(On Diff #37707)

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

33 ↗(On Diff #37707)

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

46 ↗(On Diff #37707)

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

52 ↗(On Diff #37707)

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

54 ↗(On Diff #37707)

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

56 ↗(On Diff #37707)

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

74 ↗(On Diff #37707)

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 ↗(On Diff #37707)

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

78 ↗(On Diff #37707)

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

81 ↗(On Diff #37707)

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

83 ↗(On Diff #37707)

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

85 ↗(On Diff #37707)

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

93 ↗(On Diff #37707)


98 ↗(On Diff #37707)


99 ↗(On Diff #37707)

"specified value"

103 ↗(On Diff #37707)

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

105 ↗(On Diff #37707)

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

109 ↗(On Diff #37707)

".Li .gdb_index"?

113 ↗(On Diff #37707)

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

119 ↗(On Diff #37707)

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

124 ↗(On Diff #37707)

.Fl -lto-newpm-passes, presumably

126 ↗(On Diff #37707)

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

130 ↗(On Diff #37707)

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

134 ↗(On Diff #37707)

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

138 ↗(On Diff #37707)

Do we want to list possible values?

142 ↗(On Diff #37707)

I think a word or two is missing here.

150 ↗(On Diff #37707)

.Li .interp
"sections" plural?

160 ↗(On Diff #37707)

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

166 ↗(On Diff #37707)

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

176 ↗(On Diff #37707)

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

202 ↗(On Diff #37707)

does this interact with new-dtags?

205 ↗(On Diff #37707)

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

207 ↗(On Diff #37707)

Read a linker script from the path
.Ar value .

209 ↗(On Diff #37707)

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

214 ↗(On Diff #37707)

.Ar value ."

216 ↗(On Diff #37707)

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

225 ↗(On Diff #37707)

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

227 ↗(On Diff #37707)

, used for locating system libraries

233 ↗(On Diff #37707)

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

235 ↗(On Diff #37707)

.Fl -section-start
.Li .bss

237 ↗(On Diff #37707)


247 ↗(On Diff #37707)

"the indicated symbols", maybe?

251 ↗(On Diff #37707)

.Fl -section-start
.Li .text

253 ↗(On Diff #37707)

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

255 ↗(On Diff #37707)

What are the valid options?

270 ↗(On Diff #37707)

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

272 ↗(On Diff #37707)

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

284 ↗(On Diff #37707)

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

286 ↗(On Diff #37707)

This could probably have more prose, like
"The target ABIs supported by

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.

9 ↗(On Diff #37707)

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

33 ↗(On Diff #37707)

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

emaste added inline comments.
54 ↗(On Diff #37707)

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

78 ↗(On Diff #37707)

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

83 ↗(On Diff #37707)

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

85 ↗(On Diff #37707)

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

105 ↗(On Diff #37707)

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

142 ↗(On Diff #37707)

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

First round of cleanup from bjk

emaste added inline comments.
26 ↗(On Diff #37707)

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

30 ↗(On Diff #37707)

Need to check exact details.

52 ↗(On Diff #37707)

Need to investigate.

56 ↗(On Diff #37707)

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

93 ↗(On Diff #37707)

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

This revision was not accepted when it landed; it landed in state Needs Review.Jan 10 2018, 4:01 PM
This revision was automatically updated to reflect the committed changes.
130 ↗(On Diff #37707)

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

134 ↗(On Diff #37707)

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 and libfoo.a.

138 ↗(On Diff #37707)

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. added inline comments.
26 ↗(On Diff #37707)

I added some explanation in my branch

52 ↗(On Diff #37707)

I found the options and the default

wblock added inline comments.

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


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


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


Don't need the comma after "number".