Page MenuHomeFreeBSD

introduce basic lld man page
ClosedPublic

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

Details

Reviewers
bjk
Group Reviewers
manpages
Commits
rS327770: lld: introduce basic man page
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.

Diff Detail

Repository
rS FreeBSD src repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
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.

emaste added a comment.Jan 9 2018, 5:21 PM

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 updated this revision to Diff 37683.Jan 9 2018, 5:30 PM
  • add . at end of descriptions
  • wrap
  • expand -o output argument
  • use .Fn for _exit function markup
emaste updated this revision to Diff 37707.Jan 10 2018, 1:34 AM
  • Connect to Makefile
  • document -z text, -z notext
  • use .Dv for tags
bjk added a comment.Jan 10 2018, 4:01 AM

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 ↗(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)

(all?)

98 ↗(On Diff #37707)

"the"

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
and
.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)

"to
.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)

ditto

247 ↗(On Diff #37707)

"the indicated symbols", maybe?

251 ↗(On Diff #37707)

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

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
.Nm
are:"

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 ↗(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 marked 9 inline comments as done.Jan 10 2018, 2:49 PM
emaste added inline comments.
usr.bin/clang/lld/ld.lld.1
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.

emaste updated this revision to Diff 37725.Jan 10 2018, 2:49 PM

First round of cleanup from bjk

emaste marked 21 inline comments as done.Jan 10 2018, 3:12 PM
emaste added inline comments.
usr.bin/clang/lld/ld.lld.1
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
Closed by commit rS327770: lld: introduce basic man page (authored by emaste, committed by ). · Explain Why
This revision was automatically updated to reflect the committed changes.
emaste marked an inline comment as done.Jan 10 2018, 4:36 PM
emaste added inline comments.Jan 10 2018, 6:06 PM
usr.bin/clang/lld/ld.lld.1
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 libfoo.so 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.

arshankhanifar_gmail.com added inline comments.
usr.bin/clang/lld/ld.lld.1
26 ↗(On Diff #37707)

I added some explanation in my branch

52 ↗(On Diff #37707)

I found the options and the default

wblock added a subscriber: wblock.Feb 2 2018, 6:56 PM
wblock added inline comments.
head/usr.bin/clang/lld/ld.lld.1
39

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

50

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

221

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

336

Don't need the comma after "number".