Add docs for Mach-O lld

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.

Reviewed By: #lld-macho, int3

Differential Revision: https://reviews.llvm.org/D132893

3 files changed, 99 insertions, 0 deletions

diff --git a/lld/docs/MachO/index.rst b/lld/docs/MachO/index.rst
new file mode 100644
index 000000000000..69583b24f3c9
--- /dev/null
+++ b/lld/docs/MachO/index.rst
@@ -0,0 +1,61 @@
+Mach-O LLD Port
+===============
+
+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
diff --git a/lld/docs/MachO/ld64-vs-lld.rst b/lld/docs/MachO/ld64-vs-lld.rst
new file mode 100644
index 000000000000..3601c224f95b
--- /dev/null
+++ b/lld/docs/MachO/ld64-vs-lld.rst
@@ -0,0 +1,37 @@
+==================
+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.
diff --git a/lld/docs/index.rst b/lld/docs/index.rst
index 0086d7ec14f9..ce6320333243 100644
--- a/lld/docs/index.rst
+++ b/lld/docs/index.rst
@@ -168,3 +168,4 @@ document soon.
    ELF/linker_script
    ELF/start-stop-gc
    ELF/warn_backrefs
+   MachO/index