Page MenuHomePhabricator

Add initial ld.lld.1 man page
ClosedPublic

Authored by emaste on Feb 6 2018, 6:51 AM.

Details

Summary

One of our requirements in FreeBSD to enable lld as the system linker was that it has a man page. We created the man page in this review, and offer it for inclusion upstream.

Some options are missing detail, but it should make a good starting point.

Diff Detail

Repository
rLLD LLVM Linker

Event Timeline

emaste created this revision.Feb 6 2018, 6:51 AM
emaste updated this revision to Diff 133032.Feb 6 2018, 9:38 AM
  • Update copyright and license statement
  • Remove internal -full-shutdown option
krytarowski added inline comments.Feb 6 2018, 9:47 AM
docs/ld.lld.1
5

Can we put this to .Sh HISTORY?

ruiu added a comment.Feb 6 2018, 3:04 PM

Thank you for doing this!

docs/ld.lld.1
49

"md5", "sha1", "tree", "uuid", 0x<hexstring> (e.g. 0xdeadbeef) and "none" are accepted. tree is a synonym to sha1.

53–56

-color-diagnostics={auto,always,never}

  • "auto" enables color output only when output is a terminal. It disables color output if the output is not a terminal (it uses isatty() internally.)

-color-diagnostics is a synonym to -color-diagnostics=auto

57

-compress-debug-sections={none,zlib}

If zlib is specified, lld compresses debug sections in output.

61

-defsym=symbol=expression

expression can either be another symbol or a linker script expression. E.g.

-defsym=foo=bar
-defysm=foo=bar+0x100

122

both is default.

182

-no-pie

(-nopie was a typo and I recently fixed that.)

186–192

--oformat, --omagic, --opt-remarks-filename and --opt-remarks-with-hotness. An option that starts with "o" must be preceded by two dashes. Otherwise it's interpreted as -o foo (output file).

emaste updated this revision to Diff 133124.Feb 6 2018, 5:59 PM

Incorporate review feedback

emaste added inline comments.Feb 6 2018, 6:01 PM
docs/ld.lld.1
186–192

Fl renders the first dash, so Fl -omagic renders as --omagic.

emaste added a comment.Feb 6 2018, 6:02 PM

PDF rendered version of the man page:

emaste added inline comments.Feb 6 2018, 6:04 PM
docs/ld.lld.1
5

It seems excessive to create a .Sh HISTORY section containing only the history of the man page itself; this could perhaps be fleshed out in a subsequent commit with more history of lld and adoption in various projects?

ruiu added inline comments.Feb 6 2018, 7:29 PM
docs/ld.lld.1
115

value is a filename, and this option reads a list of dynamic symbols from a given file.

139

value is a symbol.

152

input-format is one of binary, elf or default. default is synonym for elf.

194

value is a filename.

232

Currently a format must be "binary" if this option is given, and when the option is given, it outputs an ELF header-less file.

236

value is a filename.

240–241

O0 disables string merging. O1 enables string merging. O2 enables string tail merging. O1 is the default.

270

value is a filename.

291

Ditto

336

This is the default.

337

value is a symbol name.

347

value is a symbol name.

353

value is a filename.

373

stack-size value
Set PT_GNU_STACK to a given value

max-page-size value
Override the system default maximum page size to a given value

muls
Synonym for --allow-multiple-definition

nocombreloc
Do not sort relocation section contents

execstack
Make the stack executable

nocopyreloc
Treat copy relocations as errors

nodelete
Set DF_1_NODELETE bit in DT_FLAGS_1 to 1

nodlopen
Set DF_1_NOOPEN bit in DT_FLAGS_1 to 1

now
Set DF_BIND_NOW bit

origin
Set DF_ORIGIN bit

norelro
Do not emit PT_GNU_RELRO segment

retpolineplt
Emit a PLT that mitigates Spectre v2 vulnerability

rodynamic
Make .dynamic section read-only

wxneeded
Create a PT_OPENBSD_WXNEEDED segment

grimar added a subscriber: grimar.Feb 6 2018, 11:50 PM
grimar added inline comments.
docs/ld.lld.1
386

Is "The targets supported by" part needed ? Please see comments for D42952 and D42992, we
changed help to print just "elf" instead.
(and btw, this list has 2 missing targets currently as mentioned in description of D42952).

emaste marked 14 inline comments as done.Feb 7 2018, 6:13 AM
emaste added inline comments.
docs/ld.lld.1
232

Should we accept elf also?

emaste updated this revision to Diff 133209.Feb 7 2018, 6:14 AM
emaste marked an inline comment as done.
emaste added a comment.Feb 7 2018, 6:16 AM

PDF version of current version:

emaste added inline comments.Feb 7 2018, 6:20 AM
docs/ld.lld.1
409

Not sure how this 稙 character ended up here, but it is fixed locally.

emaste marked an inline comment as done.Feb 7 2018, 6:42 AM
krytarowski added inline comments.Feb 7 2018, 6:48 AM
docs/ld.lld.1
5

I propose something like this:

.Sh HISTORY
This man page first appeared in
.Fx .
.Sh AUTHORS
.An Ed Maste Aq Mt ed@FreeBSD.org

A hidden comment has little added value.

ruiu accepted this revision.Feb 7 2018, 11:18 AM

Looking pretty good! LGTM

docs/ld.lld.1
267

01 -> O1
02 -> O2

This revision is now accepted and ready to land.Feb 7 2018, 11:18 AM
emaste marked an inline comment as done.Feb 7 2018, 12:08 PM

Thanks, I'll commit this later today. Not sure how I ended up with 01 instead of O1 but have fixed those locally.

I'd to have an "implementation details" section explaining (at least) the way lld does symbol resolution and how it differs from bfd/gold but that can be a later commit; perhaps you have notes from one of your talks already that could be dropped in.

This revision was automatically updated to reflect the committed changes.
emaste added inline comments.Feb 7 2018, 12:42 PM
docs/ld.lld.1
5

I'll come back to this for a future commit.