2020-10-21 08:55:50 +03:00
|
|
|
# mold: A Modern Linker
|
2020-10-21 06:52:11 +03:00
|
|
|
|
2023-03-22 11:35:22 +03:00
|
|
|
mold is a faster drop-in replacement for existing Unix linkers. It is several
|
2023-03-22 11:36:05 +03:00
|
|
|
times quicker than the LLVM lld linker, the second-fastest open-source linker,
|
|
|
|
which I initially developed a few years ago. mold aims to enhance developer
|
|
|
|
productivity by minimizing build time, particularly in rapid
|
2023-03-22 11:35:22 +03:00
|
|
|
debug-edit-rebuild cycles.
|
2020-10-21 06:52:11 +03:00
|
|
|
|
2024-02-24 09:08:05 +03:00
|
|
|
Here is a performance comparison of GNU ld, GNU gold, LLVM lld, and
|
|
|
|
mold when linking final debuginfo-enabled executables for major large
|
|
|
|
programs on a simulated 16-core, 32-thread machine.
|
2021-03-21 07:51:34 +03:00
|
|
|
|
2024-02-24 08:56:47 +03:00
|
|
|
![Link speed comparison](docs/chart.svg)
|
2021-03-21 07:51:34 +03:00
|
|
|
|
2024-02-24 08:56:47 +03:00
|
|
|
| Program (linker output size) | GNU ld | GNU gold | LLVM lld | mold
|
|
|
|
|-------------------------------|--------|----------|----------|------
|
|
|
|
| MySQL 8.3 (0.47 GiB) | 10.84s | 7.47s | 1.64s | 0.46s
|
|
|
|
| Clang 19 (1.56 GiB) | 42.07s | 33.13s | 5.20s | 1.35s
|
|
|
|
| Chromium 124 (1.35 GiB) | N/A | 27.40s | 6.10s | 1.52s
|
2021-12-13 09:28:26 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
mold is so fast that it is only 2x _slower_ than the `cp` command on the same
|
2024-02-24 09:07:19 +03:00
|
|
|
machine. If you find that mold is not faster than other linkers, feel
|
2023-03-22 11:36:05 +03:00
|
|
|
free to [file a bug report](https://github.com/rui314/mold/issues).
|
2021-03-21 07:51:34 +03:00
|
|
|
|
2022-10-01 06:22:24 +03:00
|
|
|
mold supports x86-64, i386, ARM64, ARM32, 64-bit/32-bit little/big-endian
|
2023-03-22 11:35:22 +03:00
|
|
|
RISC-V, 32-bit PowerPC, 64-bit big-endian PowerPC ELFv1, 64-bit little-endian
|
2023-08-13 04:39:08 +03:00
|
|
|
PowerPC ELFv2, s390x, 64-bit/32-bit LoongArch, SPARC64, m68k, SH-4, and DEC
|
|
|
|
Alpha.
|
2021-12-15 04:44:10 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
## Why does linking speed matter?
|
2021-12-12 15:19:12 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
If you are using a compiled language such as C, C++, or Rust, a build consists
|
2023-03-22 11:35:22 +03:00
|
|
|
of two phases. In the first phase, a compiler compiles source files into
|
|
|
|
object files (`.o` files). In the second phase, a linker takes all object
|
2023-03-22 11:36:05 +03:00
|
|
|
files and combines them into a single executable or shared library file.
|
2021-04-18 15:41:36 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
The second phase can be time-consuming if your build output is large. mold can
|
|
|
|
speed up this process, saving you time and preventing distractions while
|
|
|
|
waiting for a lengthy build to finish. The difference is most noticeable
|
|
|
|
during rapid debug-edit-rebuild cycles.
|
2021-04-19 16:25:13 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
## Installation
|
2021-12-22 13:59:39 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
Binary packages for the following systems are currently available:
|
2021-12-22 13:59:39 +03:00
|
|
|
|
|
|
|
[![Packaging status](https://repology.org/badge/vertical-allrepos/mold.svg)](https://repology.org/project/mold/versions)
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
## How to Build
|
2021-03-16 19:35:32 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
mold is written in C++20, so if you build mold yourself, you will need a
|
|
|
|
recent version of a C++ compiler and a C++ standard library. We recommend GCC
|
|
|
|
10.2 or Clang 12.0.0 (or later) and libstdc++ 10 or libc++ 7 (or later).
|
2021-03-16 19:35:32 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
### Install Dependencies
|
2021-10-27 20:22:38 +03:00
|
|
|
|
2022-04-23 13:22:53 +03:00
|
|
|
To install build dependencies, run `./install-build-deps.sh` in this
|
2023-03-22 11:36:05 +03:00
|
|
|
directory. It will detect your Linux distribution and attempt to install the
|
|
|
|
necessary packages. You may need to run it as root.
|
2021-10-27 20:22:38 +03:00
|
|
|
|
|
|
|
### Compile mold
|
|
|
|
|
|
|
|
```shell
|
2024-03-28 07:08:53 +03:00
|
|
|
git clone --branch stable https://github.com/rui314/mold.git
|
|
|
|
cd mold
|
|
|
|
./install-build-deps.sh
|
|
|
|
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=c++ -B build
|
|
|
|
cmake --build build -j$(nproc)
|
|
|
|
sudo cmake --build build --target install
|
2021-03-16 19:35:32 +03:00
|
|
|
```
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
You might need to pass a C++20 compiler command name to `cmake`. In the
|
|
|
|
example above, `c++` is passed. If that doesn't work for you, try a specific
|
|
|
|
version of a compiler, such as `g++-10` or `clang++-12`.
|
2022-01-07 12:42:40 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
By default, `mold` is installed to `/usr/local/bin`. You can change the
|
|
|
|
installation location by passing `-DCMAKE_INSTALL_PREFIX=<directory>`.
|
|
|
|
For other cmake options, see the comments in `CMakeLists.txt`.
|
2021-03-24 12:38:08 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
If you are not using a recent enough Linux distribution, or if `cmake` does
|
|
|
|
not work for you for any reason, you can use Docker to build mold in a Docker
|
|
|
|
environment. To do so, run `./dist.sh` in this directory instead of using
|
|
|
|
`cmake`. The shell script will pull a Docker image, build mold and auxiliary
|
|
|
|
files inside it, and package them into a single tar file named
|
2023-03-22 11:35:22 +03:00
|
|
|
`mold-$version-$arch-linux.tar.gz`. You can extract the tar file anywhere and
|
2023-03-22 11:36:05 +03:00
|
|
|
use the mold executable within it.
|
2021-04-19 17:08:29 +03:00
|
|
|
|
2021-03-26 11:06:35 +03:00
|
|
|
## How to use
|
|
|
|
|
2021-12-27 06:14:30 +03:00
|
|
|
<details><summary>A classic way to use mold</summary>
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
On Unix, the linker command (usually `/usr/bin/ld`) is indirectly invoked by
|
|
|
|
the compiler driver (typically `cc`, `gcc`, or `clang`), which is in turn
|
2024-03-20 07:43:10 +03:00
|
|
|
indirectly invoked by `make` or other build system commands.
|
2021-12-27 06:14:30 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
If you can specify an additional command line option for your compiler driver
|
|
|
|
by modifying the build system's config files, add one of the following flags
|
|
|
|
to use mold instead of `/usr/bin/ld`:
|
2021-06-30 20:45:04 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
- For Clang: pass `-fuse-ld=mold`
|
2021-12-27 07:37:25 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
- For GCC 12.1.0 or later: pass `-fuse-ld=mold`
|
2021-12-27 07:37:25 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
- For GCC before 12.1.0: the `-fuse-ld` option does not accept `mold` as a
|
|
|
|
valid argument, so you need to use the `-B` option instead. The `-B` option
|
|
|
|
tells GCC where to look for external commands like `ld`.
|
2021-12-27 07:37:25 +03:00
|
|
|
|
2023-03-22 11:35:22 +03:00
|
|
|
If you have installed mold with `make install`, there should be a directory
|
|
|
|
named `/usr/libexec/mold` (or `/usr/local/libexec/mold`, depending on your
|
2023-03-22 11:36:05 +03:00
|
|
|
`$PREFIX`), and the `ld` command should be there. The `ld` is actually a
|
|
|
|
symlink to `mold`. So, all you need is to pass `-B/usr/libexec/mold` (or
|
2023-03-22 11:35:22 +03:00
|
|
|
`-B/usr/local/libexec/mold`) to GCC.
|
2021-12-27 06:14:30 +03:00
|
|
|
|
2022-12-30 05:53:10 +03:00
|
|
|
If you haven't installed `ld.mold` to any `$PATH`, you can still pass
|
2023-03-22 11:36:05 +03:00
|
|
|
`-fuse-ld=/absolute/path/to/mold` to clang to use mold. However, GCC does not
|
|
|
|
accept an absolute path as an argument for `-fuse-ld`.
|
2021-12-29 15:36:06 +03:00
|
|
|
|
2021-12-27 06:14:30 +03:00
|
|
|
</details>
|
|
|
|
|
|
|
|
<details><summary>If you are using Rust</summary>
|
|
|
|
|
|
|
|
Create `.cargo/config.toml` in your project directory with the following:
|
|
|
|
|
2022-08-18 20:45:55 +03:00
|
|
|
```toml
|
2021-12-27 06:14:30 +03:00
|
|
|
[target.x86_64-unknown-linux-gnu]
|
|
|
|
linker = "clang"
|
|
|
|
rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]
|
|
|
|
```
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
where `/path/to/mold` is an absolute path to the mold executable. In the
|
|
|
|
example above, we use `clang` as a linker driver since it always accepts the
|
2023-03-22 11:35:22 +03:00
|
|
|
`-fuse-ld` option. If your GCC is recent enough to recognize the option, you
|
|
|
|
may be able to remove the `linker = "clang"` line.
|
2022-10-08 20:40:30 +03:00
|
|
|
|
|
|
|
```toml
|
|
|
|
[target.x86_64-unknown-linux-gnu]
|
2022-10-09 06:32:55 +03:00
|
|
|
rustflags = ["-C", "link-arg=-fuse-ld=/path/to/mold"]
|
2022-10-08 20:40:30 +03:00
|
|
|
```
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
If you want to use mold for all projects, add the above snippet to
|
2022-10-09 06:32:55 +03:00
|
|
|
`~/.cargo/config.toml`.
|
|
|
|
|
2021-12-27 06:14:30 +03:00
|
|
|
</details>
|
|
|
|
|
2022-11-21 17:30:28 +03:00
|
|
|
<details><summary>If you are using Nim</summary>
|
|
|
|
|
|
|
|
Create `config.nims` in your project directory with the following:
|
|
|
|
|
|
|
|
```nim
|
|
|
|
when findExe("mold").len > 0 and defined(linux):
|
|
|
|
switch("passL", "-fuse-ld=mold")
|
|
|
|
```
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
where `mold` must be included in the `PATH` environment variable. In this
|
|
|
|
example, `gcc` is used as the linker driver. Use the `-fuse-ld` option if your
|
|
|
|
GCC is recent enough to recognize this option.
|
2022-11-21 17:30:28 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
If you want to use mold for all projects, add the above snippet to
|
2023-03-22 11:35:22 +03:00
|
|
|
`~/.config/config.nims`.
|
2022-11-21 17:30:28 +03:00
|
|
|
|
|
|
|
</details>
|
|
|
|
|
2021-12-27 06:14:30 +03:00
|
|
|
<details><summary>mold -run</summary>
|
2021-03-26 11:06:35 +03:00
|
|
|
|
2023-03-22 11:35:22 +03:00
|
|
|
It is sometimes very hard to pass an appropriate command line option to `cc`
|
2023-03-22 11:36:05 +03:00
|
|
|
to specify an alternative linker. To address this situation, mold has a
|
2024-03-20 07:43:10 +03:00
|
|
|
feature to intercept all invocations of `ld`, `ld.bfd`, `ld.lld`, or `ld.gold`
|
|
|
|
and redirect them to itself. To use this feature, run `make` (or another build
|
2023-03-22 11:35:22 +03:00
|
|
|
command) as a subcommand of mold as follows:
|
2021-03-24 12:38:08 +03:00
|
|
|
|
2021-10-27 20:22:38 +03:00
|
|
|
```shell
|
2021-12-13 09:28:26 +03:00
|
|
|
mold -run make <make-options-if-any>
|
2021-03-24 12:38:08 +03:00
|
|
|
```
|
|
|
|
|
2024-03-20 07:43:10 +03:00
|
|
|
Internally, mold invokes a given command with the `LD_PRELOAD` environment
|
2023-03-22 11:35:22 +03:00
|
|
|
variable set to its companion shared object file. The shared object file
|
|
|
|
intercepts all function calls to `exec(3)`-family functions to replace
|
2024-03-20 07:43:10 +03:00
|
|
|
`argv[0]` with `mold` if it is `ld`, `ld.bf`, `ld.gold`, or `ld.lld`.
|
2021-03-26 11:06:35 +03:00
|
|
|
|
2021-12-27 06:14:30 +03:00
|
|
|
</details>
|
|
|
|
|
2022-06-03 14:38:05 +03:00
|
|
|
<details><summary>GitHub Actions</summary>
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
You can use our [setup-mold](https://github.com/rui314/setup-mold) GitHub
|
|
|
|
Action to speed up GitHub-hosted continuous builds. Although GitHub Actions
|
2024-03-20 07:43:10 +03:00
|
|
|
run on a 4 core machine, mold is still significantly faster than the default
|
2023-03-22 11:36:05 +03:00
|
|
|
GNU linker, especially when linking large programs.
|
2022-06-03 14:38:05 +03:00
|
|
|
|
2022-04-10 04:03:06 +03:00
|
|
|
</details>
|
|
|
|
|
2022-02-13 09:16:05 +03:00
|
|
|
<details><summary>Verify that you are using mold</summary>
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
mold leaves its identification string in the `.comment` section of an output
|
|
|
|
file. You can print it out to verify that you are actually using mold.
|
2021-03-24 12:38:08 +03:00
|
|
|
|
2021-10-27 20:22:38 +03:00
|
|
|
```shell
|
2022-04-20 05:00:48 +03:00
|
|
|
$ readelf -p .comment <executable-file>
|
2021-03-24 12:38:08 +03:00
|
|
|
|
|
|
|
String dump of section '.comment':
|
|
|
|
[ 0] GCC: (Ubuntu 10.2.0-5ubuntu1~20.04) 10.2.0
|
|
|
|
[ 2b] mold 9a1679b47d9b22012ec7dfbda97c8983956716f7
|
|
|
|
```
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
If `mold` is present in the `.comment` section, the file was created by mold.
|
2021-03-24 12:38:08 +03:00
|
|
|
|
2022-02-13 09:16:05 +03:00
|
|
|
</details>
|
|
|
|
|
2022-08-14 10:06:15 +03:00
|
|
|
<details><summary>Online manual</summary>
|
|
|
|
|
2023-03-22 11:35:22 +03:00
|
|
|
Since mold is a drop-in replacement, you should be able to use it without
|
2023-03-22 11:36:05 +03:00
|
|
|
reading its manual. However, if you need it, [mold's man page](docs/mold.md)
|
2024-03-20 07:43:10 +03:00
|
|
|
is available online. You can read the same manual by running `man mold`.
|
2022-08-14 10:06:15 +03:00
|
|
|
|
|
|
|
</details>
|
|
|
|
|
2021-12-12 15:19:12 +03:00
|
|
|
## Why is mold so fast?
|
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
One reason is that it utilizes faster algorithms and more efficient data
|
|
|
|
structures compared to other linkers. Another reason is that mold is highly
|
|
|
|
parallelized.
|
2021-12-12 15:19:12 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
Here is a side-by-side comparison of per-core CPU usage for lld (left) and
|
|
|
|
mold (right), linking the same program, a Chromium executable.
|
2021-12-12 15:19:12 +03:00
|
|
|
|
|
|
|
![CPU usage comparison in htop animation](docs/htop.gif)
|
|
|
|
|
2023-03-22 11:35:22 +03:00
|
|
|
As you can see, mold uses all available cores throughout its execution and
|
2023-03-22 11:36:05 +03:00
|
|
|
finishes quickly. In contrast, lld fails to utilize available cores most of
|
|
|
|
the time. In this demo, the maximum parallelism is artificially capped at 16,
|
2023-03-22 11:35:22 +03:00
|
|
|
so that the bars fit in the GIF.
|
2021-12-12 15:19:12 +03:00
|
|
|
|
2023-03-22 11:36:05 +03:00
|
|
|
For details, please see the [design notes](docs/design.md).
|
2022-05-05 16:37:42 +03:00
|
|
|
|
2022-11-19 06:31:58 +03:00
|
|
|
## Sponsors
|
2022-08-04 10:22:01 +03:00
|
|
|
|
2024-03-20 07:43:10 +03:00
|
|
|
It is taken for granted nowadays that compiler toolchains can be easily
|
|
|
|
installed and used for free, and people may not think too much about the
|
|
|
|
individuals behind these "free tools". mold supports many projects, but it
|
|
|
|
is essentially a one-person project. This situation is similar to the one
|
|
|
|
depicted in the following xkcd illustration.
|
|
|
|
|
|
|
|
[![xkcd 2347](https://imgs.xkcd.com/comics/dependency.png)](https://xkcd.com/2347)
|
|
|
|
|
|
|
|
If you think that the "Nebraska guy" should be rewarded, please consider
|
|
|
|
becoming our [GitHub sponsor](https://github.com/sponsors/rui314)!
|
|
|
|
|
|
|
|
We thank everyone who sponsors our project. In particular, we'd like to acknowledge
|
|
|
|
the following people and organizations who have sponsored $128/month or more:
|
2022-08-04 10:22:01 +03:00
|
|
|
|
2022-11-19 06:31:58 +03:00
|
|
|
### Corporate sponsors
|
|
|
|
|
2023-07-29 15:13:50 +03:00
|
|
|
<a href="https://mercury.com"><img src="docs/mercury-logo.png" align=center height=120 width=400 alt=Mercury></a>
|
|
|
|
|
|
|
|
<a href="https://cybozu-global.com"><img src="docs/cyboze-logo.png" align=center height=120 width=133 alt=Cybozu></a>
|
|
|
|
|
|
|
|
<a href="https://www.emergetools.com"><img src="docs/emerge-tools-logo.png" align=center height=120 width=240 alt="Emerge Tools"></a><br>
|
2022-11-19 06:31:58 +03:00
|
|
|
|
2023-01-28 04:34:28 +03:00
|
|
|
- [G-Research](https://www.gresearch.co.uk)
|
2022-11-19 06:31:58 +03:00
|
|
|
- [Signal Slot Inc.](https://github.com/signal-slot)
|
2023-11-29 11:48:11 +03:00
|
|
|
- [GlareDB](https://github.com/GlareDB)
|
2022-11-19 06:31:58 +03:00
|
|
|
|
|
|
|
### Individual sponsors
|
|
|
|
|
2022-08-04 10:22:01 +03:00
|
|
|
- [Wei Wu](https://github.com/lazyparser)
|
2022-11-19 06:31:58 +03:00
|
|
|
- [kyle-elliott](https://github.com/kyle-elliott)
|
2023-11-29 11:48:11 +03:00
|
|
|
- [Bryant Biggs](https://github.com/bryantbiggs)
|
|
|
|
- [kraptor23](https://github.com/kraptor23)
|
|
|
|
- [Jinkyu Yi](https://github.com/jincreator)
|