This is an archive of the discontinued LLVM Phabricator instance.

Add docs for Mach-O lld
ClosedPublic

Authored by michaeleisel on Aug 29 2022, 3:27 PM.

Details

Reviewers
MaskRay
ributzka
sscalpone
int3
Group Reviewers
Restricted Project
Commits
rG0f9590af273f: Add docs for Mach-O lld
Summary

I wasn't able to find any docs for Mach-O in lld/docs, so here's an attempt at adding basic docs. One of my goals here is to make it easy for users who are unfamiliar with linkers to successfully use lld.

Diff Detail

Event Timeline

michaeleisel created this revision.Aug 29 2022, 3:27 PM
Herald added a reviewer: ributzka. · View Herald Transcript
Herald added projects: Restricted Project, Restricted Project. · View Herald Transcript
Herald added a reviewer: Restricted Project. · View Herald Transcript
michaeleisel requested review of this revision.Aug 29 2022, 3:27 PM
Herald added a project: Restricted Project. · View Herald TranscriptAug 29 2022, 3:27 PM
michaeleisel edited the summary of this revision. (Show Details)Aug 29 2022, 3:29 PM
thakis added inline comments.
lld/docs/MachO/index.rst
31

This looks very outdated. LLVM hasn't been available per SVN in a long time, and git is no longer a mirror.

56

Should this point at…uh, lld/MachO/ld64-vs-lld.rst.

Also, we should move lld/MachO/ld64-vs-lld.rst out of the source tree into the doc tree, right, @oontvoo?

michaeleisel added inline comments.Aug 31 2022, 8:01 AM
lld/docs/MachO/index.rst
56

Sure, how about another sentence saying, "For more details on the differences between ld64 and LLD, see [here](...)"? Although, I don't know what the link is. Also, can I render this somehow locally to see how it looks and if the links work?

smeenai added inline comments.
lld/docs/MachO/index.rst
56

Make sure you have sphinx-build in your path (I've found pip to be the easiest way to do this), and then set LLVM_ENABLE_SPHINX to ON in your CMakeCache.txt and reconfigure, then build the docs-lld-html target. It'll take a bit the first time, but incremental builds should be pretty quick.

oontvoo added inline comments.Aug 31 2022, 10:42 AM
lld/docs/MachO/index.rst
56

Should this point at…uh, lld/MachO/ld64-vs-lld.rst.

Also, we should move lld/MachO/ld64-vs-lld.rst out of the source tree into the doc tree, right, @oontvoo?

Yeah, I think the intention was that we'd keep this ld64-vs-lld.rst here in the source tree until the linker is "officially" released.
So now is as good a time as any.

oontvoo added inline comments.Aug 31 2022, 10:45 AM
lld/docs/MachO/index.rst
55

For future extensibility, how about rewroding this to "The user may need to add a few extra flags to match Apple's LD64. See more details at ..." ?

oontvoo added inline comments.Aug 31 2022, 10:51 AM
lld/docs/MachO/index.rst
25–26

ld64.lld is mostly just a soft link to lld, no?

45–46

[optional] but I think ninja should be used (for faster build )
Eg.,

cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld'   -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm
ninja check-lld-macho && ninja install
michaeleisel added inline comments.Aug 31 2022, 11:39 AM
lld/docs/MachO/index.rst
25–26

Correct

55

I think it would be best to have this here as a simple instruction for the user to be able to adopt lld with minimum risk, as opposed to the other doc which goes into much more depth and could be intimidating/harder to get simple action items out of. I think we could add both to here as well as well as in the ld64 vs. lld section if there are any new flags in the future to add here.

56

OK, I've moved it

Add docs for Mach-O lld

int3 added a subscriber: int3.Aug 31 2022, 1:15 PM
int3 added inline comments.
lld/docs/MachO/index.rst
2–3

looks like this was written using lld/docs/index.rst as a template, but IMO we should make it more similar to lld/docs/WebAssembly.rst -- something that's a sub-page of index.rst

(Unfortunately index.rst itself talks at length about features specific to the ELF backend w/o making it clear that those features don't apply to other ports, and we should clean that up at some point...)

55–56

I think we should rm everything in this Internals section -- no need to duplicate the top-level index.rst contents

56

yep, the intention was to make it become one of the nicely-rendered doc pages. Thanks for moving!

Add docs for Mach-O lld

Add docs for Mach-O lld

OK, I've updated the docs

lld/docs/MachO/index.rst
45–46

Done

55–56

Done

int3 accepted this revision.Sep 5 2022, 11:04 AM

lgtm, thanks for doing this!

lld/docs/MachO/index.rst
2–3

missed this one

This revision is now accepted and ready to land.Sep 5 2022, 11:04 AM

Could someone merge this? I'm not sure if I have permissions

This revision was automatically updated to reflect the committed changes.
lld/docs/MachO/index.rst