Add docs for Mach-O lld

[michaeleisel]

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.

[thakis]

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]

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]

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]

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]

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]

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]

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

[michaeleisel]

Add docs for Mach-O lld

[int3]

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!

[michaeleisel]

Add docs for Mach-O lld

[michaeleisel]

Add docs for Mach-O lld

[michaeleisel]

OK, I've updated the docs

lld/docs/MachO/index.rst

45–46

Done

55–56

Done

[int3]

lgtm, thanks for doing this!

lld/docs/MachO/index.rst

2–3

missed this one

[michaeleisel]

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

[keith]

Nice!

lld/docs/MachO/index.rst

+LLD - The LLVM Linker
+=====================
+
+LLD is a linker from the LLVM project that is a drop-in replacement
+for system linkers and runs much faster than them. It also provides
+features that are useful for toolchain developers. This document
+will describe the Mach-O port.
+
+Features
+--------
+
+- LLD is a drop-in replacement for Apple's Mach-O linker, ld64, that accepts the
+  same command line arguments.
+
+- LLD is very fast. When you link a large program on a multicore
+  machine, you can expect that LLD runs more than twice as fast as the ld64 linker.
+
+Download
+--------
+
+LLD is available as a pre-built binary by going to the `latest release <https://github.com/llvm/llvm-project/releases>`_,
+downloading the appropriate bundle (``clang+llvm-<version>-<your architecture>-<your platform>.tar.xz``),
+decompressing it, and locating the binary at ``bin/ld64.lld``. Note
+that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
+by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
+
+Build
+-----
+
+The easiest way to build LLD is to
+check out the entire LLVM projects/sub-projects from a git mirror and
+build that tree. You need `cmake` and of course a C++ compiler.
+
+.. code-block:: console
+
+  $ git clone https://github.com/llvm/llvm-project llvm-project
+  $ mkdir build
+  $ cd build
+  $ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS='lld' ../llvm-project/llvm
+  $ ninja check-lld-macho
+
+Then you can find output binary at ``build/bin/ld64.lld``. Note
+that if ``ld64.lld`` is moved out of ``bin``, it must still be accompanied
+by its sibling file ``lld``, as ``ld64.lld`` is technically a symlink to ``lld``.
+
+Using LLD
+---------
+
+LLD can be used by adding ``-fuse-ld=/path/to/ld64.lld`` to the linker flags.
+For Xcode, this can be done by adding it to "Other linker flags" in the build
+settings. For Bazel, this can be done with ``--linkopt`` or with
+[rules_apple_linker](https://github.com/keith/rules_apple_linker).
+The user may also need to add ``-Wl,--deduplicate-literals`` in order
+to match Apple's linker behavior more closely (otherwise problems
+can occur, for instance, in unit tests). For more info on
+the differences between the two, see "LD64 vs LLD-MACHO", mentioned below.
+
+.. toctree::
+   :maxdepth: 1
+
+   ld64-vs-lld

lld/docs/MachO/ld64-vs-lld.rst

 ==================
 LD64 vs LLD-MACHO
 ==================
 
 This doc lists all significant deliberate differences in behavior between LD64 and LLD-MachO.
 
 String Literal Deduplication
 ****************************
 LD64 always deduplicates string literals. LLD only does it when the ``--icf=``
 or the ``--deduplicate-literals`` flag is passed. Omitting deduplication by
 default ensures that our link is as fast as possible. However, it may also break
 some programs which have (incorrectly) relied on string deduplication always
 occurring. In particular, programs which compare string literals via pointer
 equality must be fixed to use value equality instead.
 
 String Alignment
 ****************
 LLD is slightly less conservative about aligning cstrings, allowing it to pack
 them more compactly. This should not result in any meaningful semantic
 difference.
 
 ``-no_deduplicate`` Flag
 ************************
 - LD64:
    * This turns off ICF (deduplication pass) in the linker.
 - LLD
    * This turns off ICF and string merging in the linker.
 
 ObjC Symbols Treatment
 **********************
 There are differences in how LLD and LD64 handle ObjC symbols loaded from archives.
 
 - LD64:
    * Duplicate ObjC symbols from the same archives will not raise an error. LD64 will pick the first one.
    * Duplicate ObjC symbols from different archives will raise a "duplicate symbol" error.
 - LLD:
    * Duplicate symbols, regardless of which archives they are from, will raise errors.

lld/docs/index.rst

.. toctree::
    windows_support
    missingkeyfunction
    error_handling_script
    Partitions
    ReleaseNotes
    ELF/linker_script
    ELF/start-stop-gc
    ELF/warn_backrefs
+   MachO/index