[PATCH] D49490: [docs] Update GoldPlugin documentation

[Teresa Johnson via Phabricator via llvm-commits]

This revision was automatically updated to reflect the committed changes.
Closed by commit rL337404: [docs] Update GoldPlugin documentation (authored by tejohnson, committed by ).

Repository:
  rL LLVM

https://reviews.llvm.org/D49490

Files:
  llvm/trunk/docs/GoldPlugin.rst


Index: llvm/trunk/docs/GoldPlugin.rst
===================================================================
--- llvm/trunk/docs/GoldPlugin.rst
+++ llvm/trunk/docs/GoldPlugin.rst
@@ -6,13 +6,16 @@
 ============
 
 Building with link time optimization requires cooperation from
-the system linker. LTO support on Linux systems requires that you use the
+the system linker. LTO support on Linux systems is available via the
 `gold linker`_ which supports LTO via plugins. This is the same mechanism
 used by the `GCC LTO`_ project.
 
 The LLVM gold plugin implements the gold plugin interface on top of
 :ref:`libLTO`.  The same plugin can also be used by other tools such as
-``ar`` and ``nm``.
+``ar`` and ``nm``.  Note that ld.bfd from binutils version 2.21.51.0.2
+and above also supports LTO via plugins.  However, usage of the LLVM
+gold plugin with ld.bfd is not tested and therefore not officially
+supported or recommended.
 
 .. _`gold linker`: http://sourceware.org/binutils
 .. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization
@@ -24,11 +27,20 @@
 ===============
 
 You need to have gold with plugin support and build the LLVMgold plugin.
-Check whether you have gold running ``/usr/bin/ld -v``. It will report "GNU
-gold" or else "GNU ld" if not. If you have gold, check for plugin support
-by running ``/usr/bin/ld -plugin``. If it complains "missing argument" then
-you have plugin support. If not, such as an "unknown option" error then you
-will either need to build gold or install a version with plugin support.
+The gold linker is installed as ld.gold. To see whether gold is the default
+on your system, run ``/usr/bin/ld -v``. It will report "GNU
+gold" or else "GNU ld" if not. If gold is already installed at
+``/usr/bin/ld.gold``, one option is to simply make that the default by
+backing up your existing ``/usr/bin/ld`` and creating a symbolic link
+with ``ln -s /usr/bin/ld.gold /usr/bin/ld``. Alternatively, you can build
+with clang's ``-fuse-ld=gold`` or add ``-fuse-ld=gold`` to LDFLAGS, which will
+cause the clang driver to invoke ``/usr/bin/ld.gold`` directly.
+
+If you have gold installed, check for plugin support by running
+``/usr/bin/ld.gold -plugin``. If it complains "missing argument" then
+you have plugin support. If not, and you get an error such as "unknown option",
+then you will either need to build gold or install a version with plugin
+support.
 
 * Download, configure and build gold with plugin support:
 
@@ -44,26 +56,27 @@
   the ``-plugin`` option. Running ``make`` will additionally build
   ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins.
 
+  Once you're ready to switch to using gold, backup your existing
+  ``/usr/bin/ld`` then replace it with ``ld-new``. Alternatively, install
+  in ``/usr/bin/ld.gold`` and use ``-fuse-ld=gold`` as described earlier.
+
+  Optionally, add ``--enable=gold=default`` to the above configure invocation
+  to automatically install the newly built gold as the default linker with
+  ``make install``.
+
 * Build the LLVMgold plugin. Run CMake with
   ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``.  The correct include
   path will contain the file ``plugin-api.h``.
 
 Usage
 =====
 
-The linker takes a ``-plugin`` option that points to the path of
-the plugin ``.so`` file. To find out what link command ``gcc``
-would run in a given situation, run ``gcc -v [...]`` and
-look for the line where it runs ``collect2``. Replace that with
-``ld-new -plugin /path/to/LLVMgold.so`` to test it out. Once you're
-ready to switch to using gold, backup your existing ``/usr/bin/ld``
-then replace it with ``ld-new``.
-
 You should produce bitcode files from ``clang`` with the option
 ``-flto``. This flag will also cause ``clang`` to look for the gold plugin in
 the ``lib`` directory under its prefix and pass the ``-plugin`` option to
-``ld``. It will not look for an alternate linker, which is why you need
-gold to be the installed system linker in your path.
+``ld``. It will not look for an alternate linker without ``-fuse-ld=gold``,
+which is why you otherwise need gold to be the installed system linker in
+your path.
 
 ``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to
 to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D49490.156106.patch
Type: text/x-patch
Size: 4303 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20180718/6fd1df4a/attachment.bin>