[lld] 7cfff0f - [lld-macho][docs] Cosmetic changes
Jez Ng via llvm-commits
llvm-commits at lists.llvm.org
Mon Sep 12 12:52:38 PDT 2022
Author: Jez Ng
Date: 2022-09-12T15:52:20-04:00
New Revision: 7cfff0f2769b8923c5d86a9c137460e8df80d4da
URL: https://github.com/llvm/llvm-project/commit/7cfff0f2769b8923c5d86a9c137460e8df80d4da
DIFF: https://github.com/llvm/llvm-project/commit/7cfff0f2769b8923c5d86a9c137460e8df80d4da.diff
LOG: [lld-macho][docs] Cosmetic changes
1. Fixed rST hyperlink syntax
2. Renamed LD64 -> ld64
3. Moved up the `-no_deduplicate` section so it is right under the
section talking about how our default dedup behavior differs; IMO
it makes more sense to read them in that order
4. De-bullet-listed some other sections so we have less whitespace in
the rendered page
5. Since the Mach-O LLD Port page has only one sub-page, don't render an
entire toctree with just one item. Use a "See also" box instead.
6. Wrap lines at 80 chars.
Reviewed By: #lld-macho, thevinster
Differential Revision: https://reviews.llvm.org/D133717
Added:
Modified:
lld/docs/MachO/index.rst
lld/docs/MachO/ld64-vs-lld.rst
Removed:
################################################################################
diff --git a/lld/docs/MachO/index.rst b/lld/docs/MachO/index.rst
index 69583b24f3c94..ced8833d1da3d 100644
--- a/lld/docs/MachO/index.rst
+++ b/lld/docs/MachO/index.rst
@@ -13,7 +13,8 @@ Features
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.
+ machine, you can expect that LLD runs more than twice as fast as the ld64
+ linker.
Download
--------
@@ -29,7 +30,7 @@ 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.
+build that tree. You need ``cmake`` and of course a C++ compiler.
.. code-block:: console
@@ -49,13 +50,16 @@ 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).
+`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
diff erences between the two, see "LD64 vs LLD-MACHO", mentioned below.
+can occur, for instance, in unit tests).
+
+.. seealso::
+
+ :doc:`ld64-vs-lld` has more info on the
diff erences between the two linkers.
.. toctree::
- :maxdepth: 1
+ :hidden:
ld64-vs-lld
diff --git a/lld/docs/MachO/ld64-vs-lld.rst b/lld/docs/MachO/ld64-vs-lld.rst
index 3601c224f95b0..4f3ae696bb962 100644
--- a/lld/docs/MachO/ld64-vs-lld.rst
+++ b/lld/docs/MachO/ld64-vs-lld.rst
@@ -1,37 +1,39 @@
-==================
-LD64 vs LLD-MACHO
-==================
+=================
+ld64 vs LLD-MachO
+=================
-This doc lists all significant deliberate
diff erences in behavior between LD64 and LLD-MachO.
+This doc lists all significant deliberate
diff erences in behavior between ld64
+and LLD-MachO.
String Literal Deduplication
****************************
-LD64 always deduplicates string literals. LLD only does it when the ``--icf=``
+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
-
diff erence.
-
``-no_deduplicate`` Flag
************************
-- LD64:
- * This turns off ICF (deduplication pass) in the linker.
-- LLD
- * This turns off ICF and string merging in the linker.
+- ld64: This turns off ICF (deduplication pass) in the linker.
+- LLD: This turns off ICF and string merging in the linker.
+
+String Alignment
+****************
+LLD is `slightly less conservative about aligning cstrings
+<https://reviews.llvm.org/D121342>`_, allowing it to pack them more compactly.
+This should not result in any meaningful semantic
diff erence.
ObjC Symbols Treatment
**********************
-There are
diff erences in how LLD and LD64 handle ObjC symbols loaded from archives.
+There are
diff erences 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
diff erent archives will raise a "duplicate symbol" error.
-- LLD:
- * Duplicate symbols, regardless of which archives they are from, will raise errors.
+- ld64:
+ 1. Duplicate ObjC symbols from the same archives will not raise an error.
+ ld64 will pick the first one.
+ 2. Duplicate ObjC symbols from
diff erent archives will raise a "duplicate
+ symbol" error.
+- LLD: Duplicate symbols, regardless of which archives they are from, will
+ raise errors.
More information about the llvm-commits
mailing list