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.
Details
Details
Diff Detail
Diff Detail
- Repository
- rS FreeBSD src repository - subversion
- Lint
Lint Not Applicable - Unit
Tests Not Applicable
Event Timeline
There are a very large number of changes, so older changes are hidden. Show Older Changes
Comment Actions
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.
Comment Actions
- add . at end of descriptions
- wrap
- expand -o output argument
- use .Fn for _exit function markup
Comment Actions
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 |
| 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 |
| 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 |
| 207 ↗ | (On Diff #37707) | Read a linker script from the path |
| 209 ↗ | (On Diff #37707) | How do we know which section this applies to? (Also, missing "the".) |
| 214 ↗ | (On Diff #37707) | "to |
| 216 ↗ | (On Diff #37707) | "Specifies the rule used to sort sections when a linker script is used." |
| 225 ↗ | (On Diff #37707) | I think "Lay out" as two words is better, here. |
| 227 ↗ | (On Diff #37707) | , used for locating system libraries |
| 233 ↗ | (On Diff #37707) | .Ar type |
| 235 ↗ | (On Diff #37707) | .Fl -section-start |
| 237 ↗ | (On Diff #37707) | ditto |
| 247 ↗ | (On Diff #37707) | "the indicated symbols", maybe? |
| 251 ↗ | (On Diff #37707) | .Fl -section-start |
| 253 ↗ | (On Diff #37707) | I'm not sure what this does; is it |
| 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? |
| 286 ↗ | (On Diff #37707) | This could probably have more prose, like |
Comment Actions
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). |
| 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. |
| 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. |
| 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. |