repo/extra/mold/README

mold
________________________________________________________________________________

mold is a multi-threaded, high-performance linker that is several times faster
than the industry-standard ones, namely, GNU ld, GNU gold or LLVM lld. It is
developed as a drop-in replacement for these linkers and command-line compatible
with them with a few exceptions. [0]

Upstream: $/rui314/mold


[000] Index
________________________________________________________________________________

* Installation ........................................................... [001]
* Setup .................................................................. [002]
  * METHOD 1 (Compiler-agnostic) ......................................... [003]
  * METHOD 2 (Clang >= 12.0) ............................................. [004]
  * METHOD 3 (GCC) ....................................................... [005]
* Usage .................................................................. [006]
* Troubleshooting ........................................................ [007]
  * Package Fails To Link With Mold ...................................... [008]
* References ............................................................. [009]


[001] Installation
________________________________________________________________________________

+------------------------------------------------------------------------------+
|                                                                              |
|  $ kiss b mold                                                               |
|                                                                              |
+------------------------------------------------------------------------------+


[002] Setup
________________________________________________________________________________

To use mold as the system linker one of the following methods must be used.
The first solution is recommended as it removes all possibility of the prior
linker being executed by mistake.


--[003] METHOD 1 (Compiler-agnostic) -------------------------------------------

  Use the alternatives system to set mold as the system linker.

  +----------------------------------------------------------------------------+
  |                                                                            |
  |  $ kiss a mold /usr/bin/ld                                                 |
  |                                                                            |
  +----------------------------------------------------------------------------+


--[004] METHOD 2 (Clang >= 12.0) -----------------------------------------------

  Add --ld-path to CFLAGS/CXXFLAGS.

  +----------------------------------------------------------------------------+
  |                                                                            |
  |  $ export CFLAGS="$CFLAGS --ld-path=/usr/bin/mold"                         |
  |  $ export CXXFLAGS="$CXXFLAGS --ld-path=/usr/bin/mold"                     |
  |                                                                            |
  +----------------------------------------------------------------------------+

  In addition to --ld-path, the following may also be needed. Please NOTE the
  implications of this warning suppression and why METHOD 1 may be the best
  solution to this problem.

  +----------------------------------------------------------------------------+
  |                                                                            |
  | $ export CFLAGS="$CFLAGS -Wno-unused-command-line-argument"                |
  | $ export CXXFLAGS="$CXXFLAGS -Wno-unused-command-line-argument"            |
  |                                                                            |
  +----------------------------------------------------------------------------+


--[005] METHOD 3 (GCC) ---------------------------------------------------------

  Add -B to CFLAGS/CXXFLAGS (GCC)

  +----------------------------------------------------------------------------+
  |                                                                            |
  |  $ export CFLAGS="$CFLAGS -B/usr/lib/mold"                                 |
  |  $ export CXXFLAGS="$CXXFLAGS -B/usr/lib/mold"                             |
  |                                                                            |
  +----------------------------------------------------------------------------+


[006] Usage
________________________________________________________________________________

Mold does not yet support all use cases. It can not be used to link the Linux
kernel (due to lack of linker script support) and It has no support for LTO
(Link Time Optimization).

With mold as the default linker, running the package manager as normal should
result in its usage. To verify that mold is being used, disable binary stripping
(KISS_STRIP=0) and run the following command on a newly built executable.

+------------------------------------------------------------------------------+
|                                                                              |
|   $ readelf -p .comment /path/to/exe                                         |
|                                                                              |
+------------------------------------------------------------------------------+

If 'mold' appears in the output, everything is setup correctly.


[007] Troubleshooting
________________________________________________________________________________


--[008] Package Fails To Link With Mold ----------------------------------------

  If a package in the official repositories fails to link with mold, open an
  issue. If a package in a third-party repository fails to link with mold, open
  an issue in their tracker. If a package you maintain fails to link (and the
  issue is in the linker), open an issue upstream.


[009] References
________________________________________________________________________________

[0] $/rui314/mold