llvm-project/lld/docs
Fangrui Song 899fdf548e [ELF] Add OVERWRITE_SECTIONS command
This implements https://sourceware.org/bugzilla/show_bug.cgi?id=26404

An `OVERWRITE_SECTIONS` command is a `SECTIONS` variant which contains several
output section descriptions. The output sections do not have specify an order.
Similar to `INSERT [BEFORE|AFTER]`, `LinkerScript::hasSectionsCommand` is not
set, so the built-in rules (see `docs/ELF/linker_script.rst`) still apply.
`OVERWRITE_SECTIONS` can be more convenient than `INSERT` because it does not
need an anchor section.

The initial syntax is intentionally narrow to facilitate backward compatible
extensions in the future. Symbol assignments cannot be used.

This feature is versatile. To list a few usage:

* Use `section : { KEEP(...) }` to retain input sections under GC
* Define encapsulation symbols (start/end) for an output section
* Use `section : ALIGN(...) : { ... }` to overalign an output section (similar to ld64 `-sectalign`)

When an output section is specified by both `OVERWRITE_SECTIONS` and
`INSERT`, `INSERT` is processed after overwrite sections. To make this work,
this patch changes `InsertCommand` to use name based matching instead of pointer
based matching. (This may cause a difference when `INSERT` moves one output
section more than once. Such duplicate commands should not be used in practice
(seems that in GNU ld the output sections may just disappear).)

A linker script can be used without -T/--script. The traditional `SECTIONS`
commands are concatenated, so a wrong rule can be more noticeable from the
section order. This feature if misused can be less noticeable, just like
`INSERT`.

Differential Revision: https://reviews.llvm.org/D103303
2021-06-13 12:41:11 -07:00
..
ELF [ELF] Add OVERWRITE_SECTIONS command 2021-06-13 12:41:11 -07:00
_static
_templates
llvm-theme
AtomLLD.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
CMakeLists.txt
Driver.rst fix yet another doc typo to cycle bots 2019-12-20 22:25:14 -05:00
NewLLD.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
Partitions.rst docs: Update partitioning docs now that the feature is fully landed. 2019-06-07 19:23:19 +00:00
README.txt
Readers.rst
ReleaseNotes.rst [ELF] Add OVERWRITE_SECTIONS command 2021-06-13 12:41:11 -07:00
WebAssembly.rst [lld][WebAssembly] Add `--export-if-defined` 2021-04-29 10:58:45 -07:00
conf.py Bump the trunk major version to 13 2021-01-26 19:37:55 -08:00
design.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
development.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
error_handling_script.rst [lld] Provide a hook to customize undefined symbols error handling 2020-11-09 13:28:48 +01:00
getting_started.rst doc: use the right url to bugzilla 2020-03-22 22:49:40 +01:00
hello.png
index.rst Provide a hook to customize missing library error handling 2020-11-03 11:01:29 +01:00
ld.lld.1 [docs] ld.lld.1: Mention -z nostart-stop-gc 2021-05-21 19:57:51 -07:00
make.bat
missingkeyfunction.rst Fix two sphinx warnings 2019-04-11 07:31:03 +00:00
open_projects.rst
partitions.dot Add IR support, ELF section and user documentation for partitioning feature. 2019-05-29 03:29:01 +00:00
partitions.svg Add IR support, ELF section and user documentation for partitioning feature. 2019-05-29 03:29:01 +00:00
sphinx_intro.rst [Docs] Modernize references to macOS 2019-05-30 16:46:22 +00:00
windows_support.rst [lld] Fix trivial typos in comments 2020-01-06 10:25:48 -08:00

README.txt

lld Documentation
=================

The lld documentation is written using the Sphinx documentation generator. It is
currently tested with Sphinx 1.1.3.

We currently use the 'nature' theme and a Beaker inspired structure.

See sphinx_intro.rst for more details.