1===========================
2lld |release| Release Notes
3===========================
4
5.. contents::
6    :local:
7
8.. only:: PreRelease
9
10  .. warning::
11     These are in-progress notes for the upcoming LLVM |release| release.
12     Release notes for previous releases can be found on
13     `the Download Page <https://releases.llvm.org/download.html>`_.
14
15Introduction
16============
17
18This document contains the release notes for the lld linker, release |release|.
19Here we describe the status of lld, including major improvements
20from the previous release. All lld releases may be downloaded
21from the `LLVM releases web site <https://llvm.org/releases/>`_.
22
23Non-comprehensive list of changes in this release
24=================================================
25
26ELF Improvements
27----------------
28* ``--package-metadata=`` has been added to create package metadata notes
29  (`D131439 <https://reviews.llvm.org/D131439>`_)
30
31* ``-z pack-relative-relocs`` is now available to support ``DT_RELR`` for glibc 2.36+.
32  (`D120701 <https://reviews.llvm.org/D120701>`_)
33* ``--no-fortran-common`` (pre 12.0.0 behavior) is now the default.
34* ``--load-pass-plugin`` has been added to load a new pass manager plugin.
35  (`D120490 <https://reviews.llvm.org/D120490>`_)
36* ``--android-memtag-{mode=,stack,heap}`` have been added to synthesize SHT_NOTE for memory tags on Android.
37  (`D119384 <https://reviews.llvm.org/D119384>`_)
38* ``FORCE_LLD_DIAGNOSTICS_CRASH`` environment variable is now available to force LLD to crash.
39  (`D128195 <https://reviews.llvm.org/D128195>`_)
40* ``--wrap`` semantics have been refined.
41  (`rG7288b85cc80f1ce5509aeea860e6b4232cd3ca01 <https://reviews.llvm.org/rG7288b85cc80f1ce5509aeea860e6b4232cd3ca01>`_)
42  (`D118756 <https://reviews.llvm.org/D118756>`_)
43  (`D124056 <https://reviews.llvm.org/D124056>`_)
44* ``--build-id={md5,sha1}`` are now implemented with truncated BLAKE3.
45  (`D121531 <https://reviews.llvm.org/D121531>`_)
46* ``--emit-relocs``: ``.rel[a].eh_frame`` relocation offsets are now adjusted.
47  (`D122459 <https://reviews.llvm.org/D122459>`_)
48* ``--emit-relocs``: fixed missing ``STT_SECTION`` when the first input section is synthetic.
49  (`D122463 <https://reviews.llvm.org/D122463>`_)
50* ``(TYPE=<value>)`` can now be used in linker scripts.
51  (`D118840 <https://reviews.llvm.org/D118840>`_)
52* Local symbol initialization is now performed in parallel.
53  (`D119909 <https://reviews.llvm.org/D119909>`_)
54  (`D120626 <https://reviews.llvm.org/D120626>`_)
55
56Breaking changes
57----------------
58
59* Archives are now parsed as ``--start-lib`` object files. If a member is neither
60  an ELF relocatable object file nor an LLVM bitcode file, ld.lld will give a warning.
61  (`D119074 <https://reviews.llvm.org/D119074>`_)
62* The GNU ld incompatible ``--no-define-common`` has been removed.
63* The obscure ``-dc``/``-dp`` options have been removed.
64  (`D119108 <https://reviews.llvm.org/D119108>`_)
65* ``-d`` is now ignored.
66* If a prevailing COMDAT group defines STB_WEAK symbol, having a STB_GLOBAL symbol in a non-prevailing group is now rejected with a diagnostic.
67  (`D120626 <https://reviews.llvm.org/D120626>`_)
68* Support for the legacy ``.zdebug`` format has been removed. Run
69  ``objcopy --decompress-debug-sections`` in case old object files use ``.zdebug``.
70  (`D126793 <https://reviews.llvm.org/D126793>`_)
71* ``--time-trace-file=<file>`` has been removed.
72  Use ``--time-trace=<file>`` instead.
73  (`D128451 <https://reviews.llvm.org/D128451>`_)
74
75COFF Improvements
76-----------------
77
78* Added autodetection of MSVC toolchain, a la clang-cl.  Also added
79  ``/winsysroot:`` support for explicit specification of MSVC toolchain
80  location, similar to clang-cl's ``/winsysroot``. For now,
81  ``/winsysroot:`` requires also passing in an explicit ``/machine:`` flag.
82  (`D118070 <https://reviews.llvm.org/D118070>`_)
83* ...
84
85MinGW Improvements
86------------------
87
88* The ``--disable-reloc-section`` option is now supported.
89  (`D127478 <https://reviews.llvm.org/D127478>`_)
90* The ``--exclude-symbols`` option is now supported.
91  (`D130118 <https://reviews.llvm.org/D130118>`_)
92
93* Support for an entirely new object file directive, ``-exclude-symbols:``,
94  has been implemented. (`D130120 <https://reviews.llvm.org/D130120>`_)
95
96MachO Improvements
97------------------
98
99* We now support proper relocation and pruning of EH frames. **Note:** this
100  comes at some performance overhead on x86_64 builds, and we recommend adding
101  the ``-femit-compact-unwind=no-compact-unwind`` compile flag to avoid it.
102  (`D129540 <https://reviews.llvm.org/D129540>`_,
103  `D122258 <https://reviews.llvm.org/D122258>`_)
104
105New flags
106#########
107
108* ``-load_hidden`` and ``-hidden-l`` are now supported.
109  (`D130473 <https://reviews.llvm.org/D130473>`_,
110  `D130529 <https://reviews.llvm.org/D130529>`_)
111* ``-alias`` is now supported. (`D129938 <https://reviews.llvm.org/D129938>`_)
112* ``-no_exported_symbols`` and  ``-exported_symbols_list <empty file>`` are now
113  supported. (`D127562 <https://reviews.llvm.org/D127562>`_)
114* ``-w`` -- to suppress warnings -- is now supported.
115  (`D127564 <https://reviews.llvm.org/D127564>`_)
116* ``-non_global_symbols_strip_list``, ``-non_global_symbols_no_strip_list``, and
117  ``-x`` are now supported. (`D126046 <https://reviews.llvm.org/D126046>`_)
118* ``--icf=safe`` is now supported.
119  (`D128938 <https://reviews.llvm.org/D128938>`_,
120  `D123752 <https://reviews.llvm.org/D123752>`_)
121* ``-why_live`` is now supported.
122  (`D120377 <https://reviews.llvm.org/D120377>`_)
123* ``-pagezero_size`` is now supported.
124  (`D118724 <https://reviews.llvm.org/D118724>`_)
125
126Improvements
127############
128
129* Linker optimization hints are now supported.
130  (`D129427 <https://reviews.llvm.org/D129427>`_,
131  `D129059 <https://reviews.llvm.org/D129059>`_,
132  `D128942 <https://reviews.llvm.org/D128942>`_,
133  `D128093 <https://reviews.llvm.org/D128093>`_)
134* Rebase opcodes are now encoded more compactly.
135  (`D130180 <https://reviews.llvm.org/D130180>`_,
136  `D128798 <https://reviews.llvm.org/D128798>`_)
137* C-strings are now aligned more compactly.
138  (`D121342 <https://reviews.llvm.org/D121342>`_)
139* ``--deduplicate-literals`` (and ``--icf={safe,all}``) now fold the
140  ``__cfstring`` section.
141  (`D130134  <https://reviews.llvm.org/D130134>`_,
142  `D120137 <https://reviews.llvm.org/D120137>`_)
143* ICF now folds the ``__objc_classrefs`` section.
144  (`D121053 <https://reviews.llvm.org/D121053>`_)
145* ICF now folds functions with identical LSDAs.
146  (`D129830 <https://reviews.llvm.org/D129830>`_)
147* STABS entries for folded functions are now omitted.
148  (`D123252 <https://reviews.llvm.org/D123252>`_)
149* ``__objc_imageinfo`` sections are now folded.
150  (`D130125 <https://reviews.llvm.org/D130125>`_)
151* Dylibs with ``LC_DYLD_EXPORTS_TRIE`` can now be read.
152  (`D129430 <https://reviews.llvm.org/D129430>`_)
153* Writing zippered dylibs is now supported.
154  (`D124887 <https://reviews.llvm.org/D124887>`_)
155* C-string literals are now included in the mapfile.
156  (`D118077 <https://reviews.llvm.org/D118077>`_)
157* Symbol names in several more diagnostics are now demangled.
158  (`D130490 <https://reviews.llvm.org/D130490>`_,
159  `D127110 <https://reviews.llvm.org/D127110>`_,
160  `D125732 <https://reviews.llvm.org/D125732>`_)
161* Source information is now included in symbol error messages.
162  (`D128425 <https://reviews.llvm.org/D128425>`_,
163  `D128184 <https://reviews.llvm.org/D128184>`_)
164* Numerous other improvements were made to diagnostic messages.
165  (`D127753 <https://reviews.llvm.org/D127753>`_,
166  `D127696 <https://reviews.llvm.org/D127696>`_,
167  `D127670 <https://reviews.llvm.org/D127670>`_,
168  `D118903 <https://reviews.llvm.org/D118903>`_,
169  `D118798 <https://reviews.llvm.org/D118798>`_)
170* Many performance and memory improvements were made.
171  (`D130000 <https://reviews.llvm.org/D130000>`_,
172  `D128298 <https://reviews.llvm.org/D128298>`_,
173  `D128290 <https://reviews.llvm.org/D128290>`_,
174  `D126800 <https://reviews.llvm.org/D126800>`_,
175  `D126785 <https://reviews.llvm.org/D126785>`_,
176  `D121052 <https://reviews.llvm.org/D121052>`_)
177* Order files and call graph sorting can now be used together.
178  (`D117354 <https://reviews.llvm.org/D117354>`_)
179* Give LTO more precise symbol resolutions, which allows optimizations to be
180  more effective.
181  (`D119506 <https://reviews.llvm.org/D119506>`_,
182  `D119372 <https://reviews.llvm.org/D119372>`_,
183  `D119767 <https://reviews.llvm.org/D119767>`_)
184* Added partial support for linking object files built with DTrace probes.
185  (`D129062 <https://reviews.llvm.org/D129062>`_)
186
187Fixes
188#####
189
190* Programs using Swift linked with the 14.0 SDK but an older deployment target
191  no longer crash at startup when running on older iOS versions. This is because
192  we now correctly support ``$ld$previous`` symbols that contain an explicit
193  symbol name. (`D130725 <https://reviews.llvm.org/D130725>`_)
194* Match ld64's behavior when an archive is specified both via
195  ``LC_LINKER_OPTION`` and via the command line.
196  (`D129556 <https://reviews.llvm.org/D129556>`_)
197* ``-ObjC`` now correctly loads archives with Swift sections.
198  (`D125250 <https://reviews.llvm.org/D125250>`_)
199* ``-lto_object_path`` now accepts a filename (instead of just a directory
200  name.) (`D129705 <https://reviews.llvm.org/D129705>`_)
201* The ``LC_UUID`` hash now includes the output file's name.
202  (`D122843 <https://reviews.llvm.org/D122843>`_)
203* ``-flat_namespace`` now correctly makes all extern symbols in a dylib
204  interposable. (`D119294 <https://reviews.llvm.org/D119294>`_)
205* Fixed compact unwind output when linking on 32-bit hosts.
206  (`D129363 <https://reviews.llvm.org/D129363>`_)
207* Exporting private symbols no longer triggers an assertion.
208  (`D124143 <https://reviews.llvm.org/D124143>`_)
209* MacOS-only ``.tbd`` files are now supported when targeting Catalyst.
210  (`D124336 <https://reviews.llvm.org/D124336>`_)
211* Thunk symbols now have local visibility, avoiding false duplicate symbol
212  errors. (`D122624 <https://reviews.llvm.org/D122624>`_)
213* Fixed handling of relocatable object files within frameworks.
214  (`D114841 <https://reviews.llvm.org/D114841>`_)
215
216WebAssembly Improvements
217------------------------
218
219