1MOLD(1) General Commands Manual MOLD(1)
2
6 mold - a modern linker
7
9 mold [option...] file...
10
12 mold is a faster drop-in replacement for the default GNU ld(1).
13 How to use
15 See https://github.com/rui314/mold#how-to-use.
16 Compatibility
18 Mold is designed to be a drop-in replacement for the GNU linkers for
19 linking user-land programs. If your user-land program cannot be built
20 due to missing command-line options, please file a bug at
21 https://github.com/rui314/mold/issues.
22 Mold supports a very limited set of linker script features, which is
24 just sufficient to read /usr/lib/x86_64-linux-gnu/libc.so on Linux sys‐
25 tems (on Linux, that file is contrary to its name not a shared library
26 but an ASCII linker script that loads a real libc.so file.)
27 Beyond that, we have no plan to support any additional linker script
29 features. The linker script is an ad-hoc, over-designed, complex lan‐
30 guage which we believe needs to be replaced by a simpler mechanism. We
31 have a plan to add a replacement for the linker script to mold instead.
32 Archive symbol resolution
34 Traditionally, Unix linkers are sensitive to the order in which input
35 files appear on the command line. They process input files from the
36 first (leftmost) file to the last (rightmost) file one-by-one. While
37 reading input files, they maintain sets of defined and undefined sym‐
38 bols. When visiting an archive file (.a files), they pull out object
39 files to resolve as many undefined symbols as possible and move on to
40 the next input file. Object files that weren't pulled out will never
41 have a chance for a second look.
42 Due to this behavior, you usually have to add archive files at the end
44 of a command line, so that when a linker reaches archive files, it
45 knows what symbols remain as undefined.
46 If you put archive files at the beginning of a command line, a linker
48 doesn't have any undefined symbols, and thus no object files will be
49 pulled out from archives. You can change the processing order by using
50 the --start-group and --end-group options, though they make a linker
51 slower.
52 mold, as well as the LLVM lld(1) linker, takes a different approach.
54 They remember which symbols can be resolved from archive files instead
55 of forgetting them after processing each archive. Therefore, mold and
56 lld(1) can "go back" in a command line to pull out object files from
57 archives if they are needed to resolve remaining undefined symbols.
58 They are not sensitive to the input file order.
59 --start-group and --end-group are still accepted by mold and lld(1) for
61 compatibility with traditional linkers, but they are silently ignored.
62 Dynamic symbol resolution
64 Some Unix linker features are difficult to understand without compre‐
65 hending the semantics of dynamic symbol resolution. Therefore, even
66 though it's not specific to mold, we'll explain it here.
67 We use "ELF module" or just "module" as a collective term to refer to
69 an executable or a shared library file in the ELF format.
70 An ELF module may have lists of imported symbols and exported symbols,
72 as well as a list of shared library names from which imported symbols
73 should be imported. The point is that imported symbols are not bound to
74 any specific shared library until runtime.
75 Here is how the Unix dynamic linker resolves dynamic symbols. Upon the
77 start of an ELF program, the dynamic linker constructs a list of ELF
78 modules which, as a whole, consist of a complete program. The exe‐
79 cutable file is always at the beginning of the list followed by its de‐
80 pendent shared libraries. An imported symbol is searched from the be‐
81 ginning of the list to the end. If two or more modules define the same
82 symbol, the one that appears first in the list takes precedence over
83 the others.
84 This Unix semantics are contrary to systems such as Windows that have a
86 two-level namespace for dynamic symbols. On Windows, for example, dy‐
87 namic symbols are represented as a tuple of (symbol-name, shared-li‐
88 brary-name), so that each dynamic symbol is guaranteed to be resolved
89 from some specific library.
90 Typically, an ELF module that exports a symbol also imports the same
92 symbol. Such a symbol is usually resolved to itself, but that's not the
93 case if a module that appears before it in the symbol search list pro‐
94 vides another definition of the same symbol.
95 Let's take malloc as an example. Assume that you define your version of
97 malloc in your main executable file. Then, all malloc calls from any
98 module are resolved to your function instead of the one in libc, be‐
99 cause the executable is always at the beginning of the dynamic symbol
100 search list. Note that even malloc calls within libc are resolved to
101 your definition since libc exports and imports malloc. Therefore, by
102 defining malloc yourself, you can overwrite a library function, and the
103 malloc in libc becomes dead code.
104 These Unix semantics are tricky and sometimes considered harmful. For
106 example, assume that you accidentally define atoi as a global function
107 in your executable that behaves completely differently from the one in
108 the C standard. Then, all atoi function calls from any modules (even
109 function calls within libc) are redirected to your function instead of
110 the one in libc, which will very likely cause a problem.
111 That is a somewhat surprising consequence for an accidental name con‐
113 flict. On the other hand, this semantic is sometimes useful because it
114 allows users to override library functions without rebuilding modules
115 containing them.
116 Whether good or bad, you should keep these semantics in mind to under‐
118 stand Unix linkers' behaviors.
119 Build reproducibility
121 mold's output is deterministic. That is, if you pass the same object
122 files and the same command-line options to the same version of mold, it
123 is guaranteed that mold produces the bit-by-bit identical output. The
124 linker's internal randomness, such as the timing of thread scheduling
125 or iteration orders of hash tables, doesn't affect the output.
126 mold does not have any host-specific default settings. This is contrary
128 to the GNU linkers, for which some configurable values, such as sys‐
129 tem-dependent library search paths, are hard-coded. mold depends only
130 on its command-line arguments.
131
133 --chroot=dir
134 Set dir as the root directory.
135 --color-diagnostics=[ auto | always | never ]
137 Show diagnostic messages in color using ANSI escape sequences.
138 auto means that mold prints out messages in color only if the
139 standard output is connected to a TTY. Default is auto.
140 --color-diagnostics
142 Synonym for --color-diagnostics=auto.
143 --no-color-diagnostics
145 Synonym for --color-diagnostics=never.
146 --fork, --no-fork
148 Spawn a child process and let it do the actual linking. When
149 linking a large program, the OS kernel can take a few hundred
150 milliseconds to terminate a mold process. --fork hides that la‐
151 tency. By default, it does fork.
152 --perf Print performance statistics.
154 --print-dependencies
156 Print out dependency information for input files.
157 Each line of the output for this option shows which file depends
159 on which file to use a specific symbol. This option is useful
160 for debugging why some object file in a static archive got
161 linked or why some shared library is kept in an output file's
162 dependency list even with --as-needed.
163 --repro
165 Archive input files, as well as a text file containing command
166 line options, in a tar file so that you can run mold with the
167 exact same inputs again. This is useful for reporting a bug with
168 a reproducer. The output filename is path/to/output.tar, where
169 path/to/output is an output filename specified by -o.
170 --reverse-sections
172 Reverse the order of input sections before assigning them the
173 offsets in the output file.
174 This option is useful for finding bugs that depend on the ini‐
176 tialization order of global objects. In C++, constructors of
177 global objects in a single source file are guaranteed to be exe‐
178 cuted in the source order, but there's no such guarantee across
179 compilation units. Usually, constructors are executed in the or‐
180 der given to the linker, but depending on it is a mistake.
181 By reversing the order of input sections using --reverse-sec‐
183 tions, you can easily test that your program works in the re‐
184 versed initialization order.
185 --run command arg...
187 Run command with mold /usr/bin/ld. Specifically, mold runs a
188 given command with the LD_PRELOAD environment set to intercept
189 exec(3) family functions and replaces argv[0] with itself if it
190 is ld, ld.gold, or ld.lld.
191 --shuffle-sections, --shuffle-sections=number
193 Randomize the output by shuffling the order of input sections
194 before assigning them the offsets in the output file. If a num‐
195 ber is given, it's used as a seed for the random number genera‐
196 tor, so that the linker produces the same output for the same
197 seed. If no seed is given, a random number is used as a seed.
198 This option is useful for benchmarking. Modern CPUs are sensi‐
200 tive to a program's memory layout. A seemingly benign change in
201 program layout, such as a small size increase of a function in
202 the middle of a program, can affect the program's performance.
203 Therefore, even if you write new code and get a good benchmark
204 result, it is hard to say whether the new code improves the pro‐
205 gram's performance; it is possible that the new memory layout
206 happens to perform better.
207 By running a benchmark multiple times with randomized memory
209 layouts using --shuffle-sections, you can isolate your program's
210 real performance number from the randomness caused by memory
211 layout changes.
212 --stats
214 Print input statistics.
215 --thread-count=count
217 Use count number of threads.
218 --threads, --no-threads
220 Use multiple threads. By default, mold uses as many threads as
221 the number of cores or 32, whichever is smaller. The reason it
222 is capped at 32 is because mold doesn't scale well beyond that
223 point. To use only one thread, pass --no-threads or
224 --thread-count=1.
225 --quick-exit, --no-quick-exit
227 Use or do not use quick_exit to exit.
228
230 --help Report usage information to stdout and exit.
231 -v, --version
233 Report version information to stdout.
234 -V Report version and target information to stdout.
236 -E, --export-dynamic, --no-export-dynamic
238 When creating an executable, using the -E option causes all
239 global symbols to be put into the dynamic symbol table, so that
240 the symbols are visible from other ELF modules at runtime.
241 By default, or if --no-export-dynamic is given, only symbols
243 that are referenced by DSOs at link-time are exported from an
244 executable.
245 -F libname, --filter=libname
247 Set the DT_FILTER dynamic section field to libname.
248 -I file, --dynamic-linker=file, --no-dynamic-linker
250 Set the dynamic linker path to file. If no -I option is given,
251 or if --no-dynamic-linker is given, no dynamic linker path is
252 set to an output file. This is contrary to the GNU linkers which
253 set a default dynamic linker path in that case. This difference
254 doesn't usually make any difference because the compiler driver
255 always passes -I to the linker.
256 -L dir, --library-path=dir
258 Add dir to the list of library search paths from which mold
259 searches libraries for the -l option.
260 Unlike the GNU linkers, mold does not have default search paths.
262 This difference doesn't usually make any difference because the
263 compiler driver always passes all necessary search paths to the
264 linker.
265 -M, --print-map
267 Write a map file to stdout.
268 -N, --omagic, --no-omagic
270 Force mold to emit an output file with an old-fashioned memory
271 layout. First, it makes the first data segment not aligned to a
272 page boundary. Second, text segments are marked as writable if
273 the option is given.
274 -S, --strip-debug
276 Omit .debug_* sections from the output file.
277 -T file, --script=file
279 Read linker script from file.
280 -X, --discard-locals
282 Discard temporary local symbols to reduce the sizes of the sym‐
283 bol table and the string table. Temporary local symbols are lo‐
284 cal symbols starting with .L. Compilers usually generate such
285 symbols for unnamed program elements such as string literals or
286 floating-point literals.
287 -e symbol, --entry=symbol:
289 -f shlib, --auxiliary=shlib
292 Set the DT_AUXILIARY dynamic section field to shlib.
293 -h libname, --soname=libname
295 Set the DT_SONAME dynamic section field to libname. This option
296 is used when creating a shared object file. Typically, when you
297 create libfoo.so, you want to pass --soname=foo to a linker.
298 -l libname
300 Search for liblibname.so or liblibname.a from library search
301 paths.
302 -m target
304 Choose a target.
305 -o file, --output=file
307 Use file as the output file name instead of the default name
308 a.out.
309 -r, --relocatable
311 Instead of generating an executable or a shared object file,
312 combine input object files to generate another object file that
313 can be used as an input to a linker.
314 --relocatable-merge-sections
316 By default, mold doesn't merge input sections by name when merg‐
317 ing input object files into a single output object file for -r.
318 For example, .text.foo and .text.bar aren't merged for -r even
319 though they are merged into .text according to the default sec‐
320 tion merging rules.
321 This option changes the behavior so that mold merges input sec‐
323 tions by name by the default section merging rules.
324 -s, --strip-all
326 Omit .symtab section from the output file.
327 -u symbol, --undefined=symbol
329 If symbol remains as an undefined symbol after reading all ob‐
330 ject files, and if there is a static archive that contains an
331 object file defining symbol, pull out the object file and link
332 it so that the output file contains a definition of symbol.
333 -y symbol, --trace-symbol=symbol
335 Trace references to symbol.
336 --Bdynamic
338 Link against shared libraries.
339 --Bstatic
341 Do not link against shared libraries.
342 --Bsymbolic
344 When creating a shared library, make global symbols export-only
345 (i.e. do not import the same symbol). As a result, references
346 within a shared library are always resolved locally, negating
347 symbol override at runtime. See "Dynamic symbol resolution" for
348 more information about symbol imports and exports.
349 --Bsymbolic-functions
351 This option has the same effect as --Bsymbolic but works only
352 for function symbols. Data symbols remain being both imported
353 and exported.
354 --Bno-symbolic
356 Cancel --Bsymbolic and --Bsymbolic-functions.
357 --Map=file
359 Write map file to file.
360 --Tbss=address
362 Alias for --section-start=.bss=address.
363 --Tdata=address
365 Alias for --section-start=.data=address.
366 --Ttext=address
368 Alias for --section-start=.text=address.
369 --allow-multiple-definition
371 Normally, the linker reports an error if there are more than one
372 definition of a symbol. This option changes the default behavior
373 so that it doesn't report an error for duplicate definitions and
374 instead use the first definition.
375 --as-needed, --no-as-needed
377 By default, shared libraries given to the linker are uncondi‐
378 tionally added to the list of required libraries in an output
379 file. However, shared libraries after --as-needed are added to
380 the list only when at least one symbol is actually used by the
381 output file. In other words, shared libraries after --as-needed
382 are not added to the list of needed libraries if they are not
383 needed by a program.
384 The --no-as-needed option restores the default behavior for sub‐
386 sequent files.
387 --build-id=[ md5 | sha1 | sha256 | uuid | 0xhexstring | none ]
389 Create a .note.gnu.build-id section containing a byte string to
390 uniquely identify an output file. sha256 compute a 256-bit cryp‐
391 tographic hash of an output file and set it to build-id. md5 and
392 sha1 compute the same hash but truncate it to 128 and 160 bits,
393 respectively, before setting it to build-id. uuid sets a random
394 128-bit UUID. 0xhexstring sets hexstring.
395 --build-id
397 Synonym for --build-id=sha256.
398 --no-build-id
400 Synonym for --build-id=none.
401 --compress-debug-sections=[ zlib | zlib-gabi | zstd | none ]
403 Compress DWARF debug info (.debug_* sections) using the zlib or
404 zstd compression algorithm. zlib-gabi is an alias for zlib.
405 --defsym=symbol=value
407 Define symbol as an alias for value.
408 value is either an integer (in decimal or hexadecimal with 0x
410 prefix) or a symbol name. If an integer is given as a value,
411 symbol is defined as an absolute symbol with the given value.
412 --default-symver
414 Use soname as a symbol version and append that version to all
415 symbols.
416 --demangle, --no-demangle
418 Demangle C++ and Rust symbols in log messages.
419 --dependency-file=file
421 Write a dependency file to file. The contents of the written
422 file is readable by make(1), which defines only one rule with
423 the linker's output file as a target and all input files as its
424 prerequisites. Users are expected to include the generated de‐
425 pendency file into a Makefile to automate the dependency manage‐
426 ment. This option is analogous to the compiler's -MM -MF op‐
427 tions.
428 --dynamic-list=file
430 Read a list of dynamic symbols from file. Same as --export-dy‐
431 namic-symbol-list, except that it implies --Bsymbolic. If file
432 does not exist in the current directory, it is searched from li‐
433 brary search paths for the sake of compatibility with GNU ld.
434 --eh-frame-hdr, --no-eh-frame-hdr
436 Create .eh_frame_hdr section.
437 --emit-relocs
439 The linker usually "consumes" relocation sections. That is, the
440 linker applies relocations to other sections, and relocation
441 sections themselves are discarded.
442 The --emit-relocs instructs the linker to leave relocation sec‐
444 tions in the output file. Some post-link binary analysis or op‐
445 timization tools such as LLVM Bolt need them.
446 --enable-new-dtags, --disable-new-dtags
448 By default, mold emits DT_RUNPATH for --rpath. If you pass
449 --disable-new-dtags, mold emits DT_RPATH for --rpath instead.
450 --execute-only
452 Traditionally, most processors require both executable and read‐
453 able bits to 1 to make the page executable, which allows machine
454 code to be read as data at runtime. This is actually what an at‐
455 tacker often does after gaining a limited control of a process
456 to find pieces of machine code they can use to gain the full
457 control of the process. As a mitigation, some recent processors
458 allows "execute-only" pages. If a page is execute-only, you can
459 call a function there as long as you know its address but can't
460 read it as data.
461 This option marks text segments execute-only. This option cur‐
463 rently works only on some ARM64 processors.
464 --exclude-libs=libraries ...
466 Mark all symbols in the given libraries hidden.
467 --export-dynamic-symbol=symbol
469 Put symbols matching symbol in the dynamic symbol table. symbol
470 may be a glob pattern in the same syntax as for the --export-dy‐
471 namic-symbol-list or --version-script options.
472 --export-dynamic-symbol-list=file
474 Read a list of dynamic symbols from file.
475 --fatal-warnings, --no-fatal-warnings
477 Treat warnings as errors.
478 --fini=symbol
480 Call symbol at unload-time.
481 --gc-sections, --no-gc-sections
483 Remove unreferenced sections.
484 --gdb-index
486 Create a .gdb_index section to speed up GNU debugger. To use
487 this, you need to compile source files with the -ggnu-pubnames
488 compiler flag.
489 --hash-style=[ sysv | gnu | both | none ]
491 Set hash style.
492 --icf=[ safe | all | none ], --no-icf
494 It is not uncommon for a program to contain many identical func‐
495 tions that differ only in name. For example, a C++ template
496 std::vector is very likely to be instantiated to the identical
497 code for std::vector<int> and std::vector<unsigned> because the
498 container cares only about the size of the parameter type. Iden‐
499 tical Code Folding (ICF) is a size optimization to identify and
500 merge such identical functions.
501 If --icf=all is given, mold tries to merge all identical func‐
503 tions. This reduces the size of the output most, but it is not a
504 "safe" optimization. It is guaranteed in C and C++ that two
505 pointers pointing two different functions will never be equal,
506 but --icf=all breaks that assumption as two identical functions
507 have the same address after merging. So a care must be taken
508 when you use this flag that your program does not depend on the
509 function pointer uniqueness.
510 --icf=safe is a flag to merge functions only when it is safe to
512 do so. That is, if a program does not take an address of a func‐
513 tion, it is safe to merge that function with other function, as
514 you cannot compare a function pointer with something else with‐
515 out taking an address of a function.
516 --icf=safe needs to be used with a compiler that supports
518 .llvm_addrsig section which contains the information as to what
519 symbols are address-taken. LLVM/Clang supports that section by
520 default. Since GCC does not support it yet, you cannot use
521 --icf=safe with GCC (it doesn't do any harm but can't optimize
522 at all.)
523 --icf=none and --no-icf disables ICF.
525 --ignore-data-address-equality
527 Make ICF to merge not only functions but also data. This option
528 should be used in combination with --icf=all.
529 --image-base=addr
531 Set the base address to addr.
532 --init=symbol
534 Call symbol at load-time.
535 --no-undefined
537 Report undefined symbols (even with --shared).
538 --noinhibit-exec
540 Create an output file even if errors occur.
541 --pack-dyn-relocs=[ relr | none ]
543 If relr is specified, all R_*_RELATIVE relocations are put into
544 .relr.dyn section instead of .rel.dyn or .rela.dyn section.
545 Since .relr.dyn section uses a space-efficient encoding scheme,
546 specifying this flag can reduce the size of the output. This is
547 typically most effective for position-independent executable.
548 Note that a runtime loader has to support .relr.dyn to run exe‐
550 cutables or shared libraries linked with --pack-dyn-relocs=relr.
551 As of 2022, only ChromeOS, Android and Fuchsia support it.
552 --package-metadata=string
554 Embed string to a .note.package section. This option is intended
555 to be used by a package management command such as rpm(8) to em‐
556 bed metadata regarding a package to each executable file.
557 --pie, --pic-executable, --no-pie, --no-pic-executable
559 Create a position-independent executable.
560 --print-gc-sections, --no-print-gc-sections
562 Print removed unreferenced sections.
563 --print-icf-sections, --no-print-icf-sections
565 Print folded identical sections.
566 --push-state, --pop-state
568 --push-state saves the current values of --as-needed,
569 --whole-archive, --static, and --start-lib. The saved values can
570 be restored by pop-state.
571 --push-state and --pop-state pairs can nest.
573 These options are useful when you want to construct linker com‐
575 mand line options programmatically. For example, if you want to
576 link libfoo.so by as-needed basis but don't want to change the
577 global state of --as-needed, you can append --push-state
578 --as-needed -lfoo --pop-state to the linker command line op‐
579 tions.
580 --relax, --no-relax
582 Rewrite machine instructions with more efficient ones for some
583 relocations. The feature is enabled by default.
584 --require-defined=symbol
586 Like --undefined, except the new symbol must be defined by the
587 end of the link.
588 --retain-symbols-file=file
590 Keep only symbols listed in file. file is a text file containing
591 a symbol name on each line. mold discards all local symbols as
592 well as global symbol that are not in file. Note that this op‐
593 tion removes symbols only from .symtab section and does not af‐
594 fect .dynsym section, which is used for dynamic linking.
595 --rpath=dir
597 Add dir to runtime search paths.
598 --section-start=section=address
600 Set address to section. address is a hexadecimal number that may
601 start with an optional 0x.
602 --shared, --Bshareable
604 Create a share library.
605 --spare-dynamic-tags=number
607 Reserve the given number of tags in .dynamic section.
608 --spare-program-headers=number
610 Reserve the given number of entries in the program header.
611 --start-lib, --end-lib
613 Handle object files between --start-lib and --end-lib as if they
614 were in an archive file. That means object files between them
615 are linked only when they are needed to resolve undefined sym‐
616 bols. The options are useful if you want to link object files
617 only when they are needed but want to avoid the overhead of run‐
618 ning ar(3).
619 --static
621 Do not link against shared libraries.
622 --sysroot=dir
624 Set target system root directory to dir.
625 --trace
627 Print name of each input file.
628 --undefined-version, --no-undefined-version
630 By default, mold warns on a symbol specified by a version script
631 or by --export-dynamic-symbol if it is not defined. You can si‐
632 lence the warning by --undefined-version.
633 --unique=pattern
635 Don't merge input sections that match the given glob pattern
636 pattern.
637 --unresolved-symbols=[ report-all | ignore-all | ignore-in-object-files
639 | ignore-in-shared-libs ]
640 How to handle undefined symbols.
641 --version-script=file
643 Read version script from file. If file does not exist in the
644 current directory, it is searched from library search paths for
645 the sake of compatibility with GNU ld.
646 --warn-common, --no-warn-common
648 Warn about common symbols.
649 --warn-once
651 Only warn once for each undefined symbol instead of warn for
652 each relocation referring an undefined symbol.
653 --warn-unresolved-symbols, --error-unresolved-symbols
655 Normally, the linker reports an error for unresolved symbols.
656 --warn-unresolved-symbols option turns it into a warning. --er‐
657 ror-unresolved-symbols option restores the default behavior.
658 --whole-archive, --no-whole-archive
660 When archive files (.a files) are given to the linker, only ob‐
661 ject files that are needed to resolve undefined symbols are ex‐
662 tracted from them and linked to an output file. --whole-archive
663 changes that behavior for subsequent archives so that the linker
664 extracts all object files and links them to an output. For exam‐
665 ple, if you are creating a shared object file and you want to
666 include all archive members to the output, you should pass
667 --whole-archive. --no-whole-archive restores the default behav‐
668 ior for subsequent archives.
669 --wrap=symbol
671 Make symbol be resolved to __wrap_symbol. The original symbol
672 can be resolved as __real_symbol. This option is typically used
673 for wrapping an existing function.
674 -z cet-report=[ warning | error | none ]
676 Intel Control-flow Enforcement Technology (CET) is a new x86
677 feature available since Tiger Lake which is released in 2020. It
678 defines new instructions to harden security to protect programs
679 from control hijacking attacks. You can tell the compiler to use
680 the feature by specifying the -fcf-protection flag.
681 -z cet-report flag is used to make sure that all object files
683 were compiled with a correct -fcf-protection flag. If warning or
684 error are given, mold prints out a warning or an error message
685 if an object file was not compiled with the compiler flag.
686 mold looks for GNU_PROPERTY_X86_FEATURE_1_IBT bit and GNU_PROP‐
688 ERTY_X86_FEATURE_1_SHSTK bit in .note.gnu.property section to
689 determine whether or not an object file was compiled with
690 -fcf-protection.
691 -z now, -z lazy
693 By default, functions referring to other ELF modules are re‐
694 solved by the dynamic linker when they are called for the first
695 time. -z now marks an executable or a shared library file so
696 that all dynamic symbols are resolved when a file is loaded to
697 memory. -z lazy restores the default behavior.
698 -z origin
700 Mark object requiring immediate $ORIGIN processing at runtime.
701 -z ibt Turn on GNU_PROPERTY_X86_FEATURE_1_IBT bit in .note.gnu.property
703 section to indicate that the output uses IBT-enabled PLT. This
704 option implies -z ibtplt.
705 -z ibtplt
707 Generate Intel Branch Tracking (IBT)-enabled PLT which is the
708 default on x86-64. This is the default.
709 -z execstack, -z noexecstack
711 By default, the pages for the stack area (i.e. the pages where
712 local variables reside) are not executable for security reasons.
713 -z execstack makes it executable. -z noexecstack restores the
714 default behavior.
715 -z keep-text-section-prefix, -z nokeep-text-section-prefix
717 Keep .text.hot, .text.unknown, .text.unlikely, .text.startup,
718 and .text.exit as separate sections in the final binary instead
719 of merging them as .text.
720 -z relro, -z norelro
722 Some sections such as .dynamic have to be writable only during
723 an executable or a shared library file is being loaded to mem‐
724 ory. Once the dynamic linker finishes its job, such sections
725 won't be mutated by anyone. As a security mitigation, it is pre‐
726 ferred to make such segments read-only during program execution.
727 -z relro puts such sections into a special segment called relro.
729 The dynamic linker makes a relro segment read-only after it fin‐
730 ishes its job.
731 By default, mold generates a relro segment. -z norelro disables
733 the feature.
734 -z sectionheader, -z nosectionheader
736 -z nosectionheader tell the linker to omit the section header.
737 By default, the linker does not omit the section header.
738 -z separate-loadable-segments, -z separate-code, -z noseparate-code
740 If one memory page contains multiple segments, the page protec‐
741 tion bits are set in such a way that the needed attributes
742 (writable or executable) are satisfied for all segments. This
743 usually happens at a boundary of two segments with two different
744 attributes.
745 separate-loadable-segments adds paddings between segments with
747 different attributes so that they do not share the same page.
748 This is the default.
749 separate-code adds paddings only between executable and non-exe‐
751 cutable segments.
752 noseparate-code does not add any paddings between segments.
754 -z defs, -z nodefs
756 Report undefined symbols (even with --shared).
757 -z shstk
759 Enforce shadow stack by turning GNU_PROPERTY_X86_FEATURE_1_SHSTK
760 bit in .note.gnu.property output section. Shadow stack is part
761 of Intel Control-flow Enforcement Technology (CET), which is
762 available since Tiger Lake (2020).
763 -z text, -z notext, -z textoff
765 mold by default reports an error if dynamic relocations are cre‐
766 ated in read-only sections. If -z notext or -z textoff are
767 given, mold creates such dynamic relocations without reporting
768 an error. -z text restores the default behavior.
769 -z max-page-size=number
771 Some CPU ISAs support multiple different memory page sizes. This
772 option specifies the maximum page size that an output binary can
773 run on. The default value is 4 KiB for i386, x86-64, and RISC-V,
774 and 64 KiB for ARM64.
775 -z nodefaultlib
777 Make the dynamic loader ignore default search paths.
778 -z nodelete
780 Mark DSO non-deletable at runtime.
781 -z nodlopen
783 Mark DSO not available to dlopen(3). This option makes it possi‐
784 ble for the linker to optimize thread-local variable accesses by
785 rewriting instructions for some targets.
786 -z nodump
788 Mark DSO not available to dldump(3).
789 -z nocopyreloc
791 Do not create copy relocations.
792 -z initfirst
794 Mark DSO to be initialized first at runtime.
795 -z interpose
797 Mark object to interpose all DSOs but executable.
798 -(, -), -EL, -Onumber, --allow-shlib-undefined, --dc, --dp,
800 --end-group, --no-add-needed, --no-allow-shlib-undefined,
801 --no-copy-dt-needed-entries, --no-fatal-warnings, --nostdlib,
802 --rpath-link=Ar dir, --sort-common, --sort-section, --start-group,
803 --warn-constructors, --warn-once, --fix-cortex-a53-835769, --fix-cor‐
804 tex-a53-843419, -z combreloc, -z common-page-size, -z nocombreloc
805 Ignored
806
808 MOLD_JOBS
809 If this variable is set to 1, only one mold process will run at
810 a time. If a new mold process is initiated while another is al‐
811 ready active, the new process will wait until the active one
812 completes before starting.
813 The primary reason for this environment variable is to minimize
815 peak memory usage. Since mold is designed to operate with high
816 parallelism, running multiple mold instances simultaneously may
817 not be beneficial. If you execute N instances of mold concur‐
818 rently, it could require N times the time and N times the mem‐
819 ory. On the other hand, running them one after the other might
820 still take N times longer, but the peak memory usage would be
821 the same as running just a single instance.
822 If your build system invokes multiple linker processes simulta‐
824 neously and some of them often get killed due to out-of-memory
825 errors, you might consider setting this environment variable to
826 1 to see if it addresses the OOM issue.
827 Currently, any value other than 1 is silently ignored.
829 MOLD_DEBUG
831 If this variable is set to a non-empty string, mold embeds its
832 command-line options in the output file's .comment section.
833 MOLD_REPRO
835 Setting this variable to a non-empty string has the same effect
836 as passing the --repro option.
837
839 gold(1), ld(1), elf(5), ld.so(8)
840
842 Rui Ueyama ruiu@cs.stanford.edu
843
845 Report bugs to https://github.com/rui314/mold/issues.
846 November 2023 MOLD(1)