diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/NewLLD.rst | 8 | ||||
| -rw-r--r-- | docs/Partitions.rst | 116 | ||||
| -rw-r--r-- | docs/ReleaseNotes.rst | 63 | ||||
| -rw-r--r-- | docs/WebAssembly.rst | 78 | ||||
| -rw-r--r-- | docs/conf.py | 4 | ||||
| -rw-r--r-- | docs/getting_started.rst | 35 | ||||
| -rw-r--r-- | docs/index.rst | 4 | ||||
| -rw-r--r-- | docs/ld.lld.1 | 119 | ||||
| -rw-r--r-- | docs/missingkeyfunction.rst | 35 | ||||
| -rw-r--r-- | docs/partitions.dot | 22 | ||||
| -rw-r--r-- | docs/partitions.svg | 110 | ||||
| -rw-r--r-- | docs/sphinx_intro.rst | 4 |
12 files changed, 493 insertions, 105 deletions
diff --git a/docs/NewLLD.rst b/docs/NewLLD.rst index 79bdf90c6ccd..d01fb53b953f 100644 --- a/docs/NewLLD.rst +++ b/docs/NewLLD.rst @@ -307,3 +307,11 @@ Glossary On Unix, your program is generally not guaranteed to be safe with ICF, although large programs happen to work correctly. LLD works fine with ICF for example. + +Other Info +---------- + +.. toctree:: + :maxdepth: 1 + + missingkeyfunction diff --git a/docs/Partitions.rst b/docs/Partitions.rst new file mode 100644 index 000000000000..e9113087631a --- /dev/null +++ b/docs/Partitions.rst @@ -0,0 +1,116 @@ +Partitions +========== + +.. warning:: + + This feature is currently experimental, and its interface is subject + to change. + +LLD's partitioning feature allows a program (which may be an executable +or a shared library) to be split into multiple pieces, or partitions. A +partitioned program consists of a main partition together with a number of +loadable partitions. The loadable partitions depend on the main partition +in a similar way to a regular ELF shared object dependency, but unlike a +shared object, the main partition and the loadable partitions share a virtual +address space at link time, and each loadable partition is assigned a fixed +offset from the main partition. This allows the loadable partitions to refer +to code and data in the main partition directly without the binary size and +performance overhead of PLTs, GOTs or symbol table entries. + +Usage +----- + +A program that uses the partitioning feature must decide which symbols are +going to be used as the "entry points" for each partition. An entry point +could, for example, be the equivalent of the partition's ``main`` function, or +there could be a group of functions that expose the functionality implemented +by the partition. The intent is that in order to use a loadable partition, +the program will use ``dlopen``/``dlsym`` or similar functions to dynamically +load the partition at its assigned address, look up an entry point by name +and call it. Note, however, that the standard ``dlopen`` function does not +allow specifying a load address. On Android, the ``android_dlopen_ext`` +function may be used together with the ``ANDROID_DLEXT_RESERVED_ADDRESS`` +flag to load a shared object at a specific address. + +Once the entry points have been decided, the translation unit(s) +containing the entry points should be compiled using the Clang compiler flag +``-fsymbol-partition=<soname>``, where ``<soname>`` is the intended soname +of the partition. The resulting object files are passed to the linker in +the usual way. + +The linker will then use these entry points to automatically split the program +into partitions according to which sections of the program are reachable from +which entry points, similarly to how ``--gc-sections`` removes unused parts of +a program. Any sections that are only reachable from a loadable partition's +entry point are assigned to that partition, while all other sections are +assigned to the main partition, including sections only reachable from +loadable partitions. + +The following diagram illustrates how sections are assigned to partitions. Each +section is colored according to its assigned partition. + +.. image:: partitions.svg + +The result of linking a program that uses partitions is essentially an +ELF file with all of the partitions concatenated together. This file is +referred to as a combined output file. To extract a partition from the +combined output file, the ``llvm-objcopy`` tool should be used together +with the flag ``--extract-main-partition`` to extract the main partition, or +``-extract-partition=<soname>`` to extract one of the loadable partitions. +An example command sequence is shown below: + +.. code-block:: shell + + # Compile the main program. + clang -ffunction-sections -fdata-sections -c main.c + + # Compile a feature to be placed in a loadable partition. + # Note that this is likely to be a separate build step to the main partition. + clang -ffunction-sections -fdata-sections -fsymbol-partition=libfeature.so -c feature.c + + # Link the combined output file. + clang main.o feature.o -fuse-ld=lld -shared -o libcombined.so -Wl,-soname,libmain.so -Wl,--gc-sections + + # Extract the partitions. + llvm-objcopy libcombined.so libmain.so --extract-main-partition + llvm-objcopy libcombined.so libfeature.so --extract-partition=libfeature.so + +In order to allow a program to discover the names of its loadable partitions +and the locations of their reserved regions, the linker creates a partition +index, which is an array of structs with the following definition: + +.. code-block:: c + + struct partition_index_entry { + int32_t name_offset; + int32_t addr_offset; + uint32_t size; + }; + +The ``name_offset`` field is a relative pointer to a null-terminated string +containing the soname of the partition, the ``addr_offset`` field is a +relative pointer to its load address and the ``size`` field contains the +size of the region reserved for the partition. To derive an absolute pointer +from the relative pointer fields in this data structure, the address of the +field should be added to the value stored in the field. + +The program may discover the location of the partition index using the +linker-defined symbols ``__part_index_begin`` and ``__part_index_end``. + +Restrictions +------------ + +This feature is currently only supported in the ELF linker. + +The partitioning feature may not currently be used together with the +``SECTIONS`` or ``PHDRS`` linker script features, nor may it be used with the +``--section-start``, ``-Ttext``, ``-Tdata`` or ``-Tbss`` flags. All of these +features assume a single set of output sections and/or program headers, which +makes their semantics ambiguous in the presence of more than one partition. + +The partitioning feature may not currently be used on the MIPS architecture +because it is unclear whether the MIPS multi-GOT ABI is compatible with +partitions. + +The current implementation only supports creating up to 254 partitions due +to implementation limitations. This limit may be relaxed in the future. diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst index dc5df6795d99..76207fec11ac 100644 --- a/docs/ReleaseNotes.rst +++ b/docs/ReleaseNotes.rst @@ -1,19 +1,19 @@ ======================= -lld 8.0.0 Release Notes +lld 9.0.0 Release Notes ======================= .. contents:: :local: .. warning:: - These are in-progress notes for the upcoming LLVM 8.0.0 release. + These are in-progress notes for the upcoming LLVM 9.0.0 release. Release notes for previous releases can be found on `the Download Page <https://releases.llvm.org/download.html>`_. Introduction ============ -This document contains the release notes for the lld linker, release 8.0.0. +This document contains the release notes for the lld linker, release 9.0.0. Here we describe the status of lld, including major improvements from the previous release. All lld releases may be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_. @@ -24,47 +24,43 @@ Non-comprehensive list of changes in this release ELF Improvements ---------------- -* lld now supports RISC-V. (`r339364 - <https://reviews.llvm.org/rL339364>`_) +* ld.lld now has typo suggestions for flags: + ``$ ld.lld --call-shared`` now prints + ``unknown argument '--call-shared', did you mean '--call_shared'``. -* Default image base address has changed from 65536 to 2 MiB for i386 - and 4 MiB for AArch64 to make lld-generated executables work better - with automatic superpage promotion. FreeBSD can promote contiguous - non-superpages to a superpage if they are aligned to the superpage - size. (`r342746 <https://reviews.llvm.org/rL342746>`_) +* ... -* lld/Hexagon can now link Linux kernel and musl libc for Qualcomm - Hexagon ISA. +COFF Improvements +----------------- -* Initial MSP430 ISA support has landed. +* Like the ELF driver, lld-link now has typo suggestions for flags. -* The following flags have been added: ``-z interpose``, ``-z global`` +* lld-link now correctly reports duplicate symbol errors for obj files + that were compiled with /Gy. -COFF Improvements ------------------ +* lld-link now correctly reports duplicate symbol errors when several res + input files define resources with the same type, name, and language. + This can be demoted to a warning using ``/force:multipleres``. + +* Having more than two ``/natvis:`` now works correctly; it used to not + work for larger binaries before. -* PDB GUID is set to hash of PDB contents instead to a random byte - sequence for build reproducibility. +* Undefined symbols are now printed only in demangled form. Pass + ``/demangle:no`` to see raw symbol names instead. -* The following flags have been added: ``/force:multiple`` +* The following flags have been added: ``/functionpadmin``, ``/swaprun:``, + ``/threads:no`` -* lld now can link against import libraries produced by GNU tools. +* Several speed and memory usage improvements. -* lld can create thunks for ARM, to allow linking images over 16 MB. +* ... MinGW Improvements ------------------ -* lld can now automatically import data variables from DLLs without the - use of the dllimport attribute. - -* lld can now use existing normal MinGW sysroots with import libraries and - CRT startup object files for GNU binutils. lld can handle most object - files produced by GCC, and thus works as a drop-in replacement for - ld.bfd in such environments. (There are known issues with linking crtend.o - from GCC in setups with DWARF exceptions though, where object files are - linked in a different order than with GNU ld, inserting a DWARF exception - table terminator too early.) +* lld now correctly links crtend.o as the last object file, handling + terminators for the sections such as .eh_frame properly, fixing + DWARF exception handling with libgcc and gcc's crtend.o. MachO Improvements ------------------ @@ -74,7 +70,4 @@ MachO Improvements WebAssembly Improvements ------------------------ -* Add initial support for creating shared libraries (-shared). - Note: The shared library format is still under active development and may - undergo significant changes in future versions. - See: https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md +* ... diff --git a/docs/WebAssembly.rst b/docs/WebAssembly.rst index 424c1a10c7e7..41522163bb85 100644 --- a/docs/WebAssembly.rst +++ b/docs/WebAssembly.rst @@ -4,21 +4,17 @@ WebAssembly lld port The WebAssembly version of lld takes WebAssembly binaries as inputs and produces a WebAssembly binary as its output. For the most part it tries to mimic the behaviour of traditional ELF linkers and specifically the ELF lld port. Where -possible that command line flags and the semantics should be the same. +possible the command line flags and the semantics should be the same. Object file format ------------------ -The format the input object files that lld expects is specified as part of the -the WebAssembly tool conventions -https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md. - -This is object format that the llvm will produce when run with the -``wasm32-unknown-unknown`` target. To build llvm with WebAssembly support -currently requires enabling the experimental backed using -``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``. +The WebAssembly object file format used by LLVM and LLD is specified as part of +the WebAssembly tool conventions on linking_. +This is the object format that the llvm will produce when run with the +``wasm32-unknown-unknown`` target. Usage ----- @@ -88,10 +84,52 @@ WebAssembly-specific options: By default the function table is neither imported nor exported, but defined for internal use only. -When building shared libraries symbols are exported if they are marked -as ``visibility=default``. When building executables only the entry point is -exported by default. In addition any symbol included on the command line via -``--export`` is also exported. +Behaviour +--------- + +In general, where possible, the WebAssembly linker attempts to emulate the +behaviour of a traditional ELF linker, and in particular the ELF port of lld. +For more specific details on how this is achieved see the tool conventions on +linking_. + +Function Signatures +~~~~~~~~~~~~~~~~~~~ + +One way in which the WebAssembly linker differs from traditional native linkers +is that function signature checking is strict in WebAssembly. It is a +validation error for a module to contain a call site that doesn't agree with +the target signature. Even though this is undefined behaviour in C/C++, it is not +uncommon to find this in real-world C/C++ programs. For example, a call site in +one compilation unit which calls a function defined in another compilation +unit but with too many arguments. + +In order not to generate such invalid modules, lld has two modes of handling such +mismatches: it can simply error-out or it can create stub functions that will +trap at runtime (functions that contain only an ``unreachable`` instruction) +and use these stub functions at the otherwise invalid call sites. + +The default behaviour is to generate these stub function and to produce +a warning. The ``--falal-warnings`` flag can be used to disable this behaviour +and error out if mismatched are found. + +Imports and Exports +~~~~~~~~~~~~~~~~~~~ + +When building a shared library any symbols marked as ``visibility=default`` will +be exported. When building an executable, only the entry point and symbols +flagged as ``WASM_SYMBOL_EXPORTED`` are exported by default. In LLVM the +``WASM_SYMBOL_EXPORTED`` flag is applied to any symbol in the ``llvm.used`` list +which corresponds to ``__attribute__((used))`` in C/C++ sources. + +In addition, symbols can be exported via the linker command line using +``--export``. + +Finally, just like with native ELF linker the ``--export-dynamic`` flag can be +used to export symbol in the executable which are marked as +``visibility=default``. + +Garbage Collection +~~~~~~~~~~~~~~~~~~ Since WebAssembly is designed with size in mind the linker defaults to ``--gc-sections`` which means that all unused functions and data segments will @@ -103,6 +141,18 @@ The symbols which are preserved by default are: - Any symbol which is to be exported. - Any symbol transitively referenced by the above. +Weak Undefined Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +On native platforms, calls to weak undefined functions end up as calls to the +null function pointer. With WebAssembly, direct calls must reference a defined +function (with the correct signature). In order to handle this case the linker +will generate function a stub containing only the ``unreachable`` instruction +and use this for any direct references to an undefined weak function. + +For example a runtime call to a weak undefined function ``foo`` will up trapping +on ``unreachable`` inside and linker-generated function called +``undefined:foo``. Missing features ---------------- @@ -112,3 +162,5 @@ Missing features - No support for creating shared libraries. The spec for shared libraries in WebAssembly is still in flux: https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md + +.. _linking: https://github.com/WebAssembly/tool-conventions/blob/master/Linking.md diff --git a/docs/conf.py b/docs/conf.py index 62404b275450..dd65859fe121 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,9 +48,9 @@ copyright = u'2011-%d, LLVM Project' % date.today().year # built documents. # # The short version. -version = '8' +version = '9' # The full version, including alpha/beta/rc tags. -release = '8' +release = '9' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 97c3d1bccbda..a174f652e736 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -28,23 +28,15 @@ On Unix-like Systems .. _libc++: http://libcxx.llvm.org/ .. _Python 2.4: http://python.org/download/ -2. Check out LLVM:: +2. Check out LLVM and subprojects (including lld):: - $ cd path/to/llvm-project - $ svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm - -3. Check out lld:: - - $ cd llvm/tools - $ svn co http://llvm.org/svn/llvm-project/lld/trunk lld - - * lld can also be checked out to ``path/to/llvm-project`` and built as an external - project. + $ git clone https://github.com/llvm/llvm-project.git 4. Build LLVM and lld:: - $ cd path/to/llvm-build/llvm (out of source build required) - $ cmake -G "Unix Makefiles" path/to/llvm-project/llvm + $ cd llvm-project + $ mkdir build && cd build + $ cmake -G "Unix Makefiles" -DLLVM_ENABLE_PROJECTS=lld ../llvm $ make * If you want to build with clang and it is not the default compiler or @@ -71,23 +63,12 @@ Using Visual Studio .. _Visual Studio 12 (2013) or later: http://www.microsoft.com/visualstudio/11/en-us .. _Python 2.4: http://python.org/download/ -#. Check out LLVM:: - - $ cd path/to/llvm-project - $ svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm - -#. Check out lld:: - - $ cd llvm/tools - $ svn co http://llvm.org/svn/llvm-project/lld/trunk lld - - * lld can also be checked out to ``path/to/llvm-project`` and built as an external - project. +#. Check out LLVM as above. #. Generate Visual Studio project files:: - $ cd path/to/llvm-build/llvm (out of source build required) - $ cmake -G "Visual Studio 11" path/to/llvm-project/llvm + $ cd llvm-project/build (out of source build required) + $ cmake -G "Visual Studio 11" -DLLVM_ENABLE_PROJECTS=lld ../llvm #. Build diff --git a/docs/index.rst b/docs/index.rst index da1c894f3d83..9056d1c2de15 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -106,7 +106,7 @@ build that tree. You need `cmake` and of course a C++ compiler. .. code-block:: console - $ git clone https://github.com/llvm-project/llvm-project-20170507 llvm-project + $ git clone https://github.com/llvm/llvm-project llvm-project $ mkdir build $ cd build $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm @@ -173,4 +173,6 @@ document soon. AtomLLD WebAssembly windows_support + missingkeyfunction + Partitions ReleaseNotes diff --git a/docs/ld.lld.1 b/docs/ld.lld.1 index d1ce4a3517f4..c432aacf7f73 100644 --- a/docs/ld.lld.1 +++ b/docs/ld.lld.1 @@ -1,9 +1,10 @@ -.\" This file is distributed under the University of Illinois Open Source -.\" License. See LICENSE.TXT for details. +.\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +.\" See https://llvm.org/LICENSE.txt for license information. +.\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception .\" .\" This man page documents only lld's ELF linking support, obtained originally .\" from FreeBSD. -.Dd September 26, 2018 +.Dd May 12, 2019 .Dt LD.LLD 1 .Os .Sh NAME @@ -45,6 +46,9 @@ as a native linker as well as a cross linker. .It Fl -allow-multiple-definition Do not error if a symbol is defined multiple times. The first definition will be used. +.It Fl -allow-shlib-undefined +Allow unresolved references in shared libraries. +This option is enabled by default when linking a shared library. .It Fl -apply-dynamic-relocs Apply link-time values for dynamic relocations. .It Fl -as-needed @@ -178,6 +182,8 @@ Set the field to the specified value. .It Fl -fini Ns = Ns Ar symbol Specify a finalizer function. +.It Fl -force-bti +Force enable AArch64 BTI instruction in PLT, warn if Input ELF file does not have GNU_PROPERTY_AARCH64_FEATURE_1_BTI property. .It Fl -format Ns = Ns Ar input-format , Fl b Ar input-format Specify the format of the inputs following this option. .Ar input-format @@ -213,6 +219,15 @@ Enable identical code folding. Enable safe identical code folding. .It Fl -icf Ns = Ns Cm none Disable identical code folding. +.It Fl -ignore-data-address-equality +Ignore address equality of data. C/C++ requires each data to have a unique +address. This option allows lld to do unsafe optimization that breaks the +requirement: create copies of read-only data or merge two or more read-only data +that happen to have the same value. +.It Fl -ignore-function-address-equality +Ignore address equality of functions. This option allows non-PIC calls to a +function with non-default visibility in a shared object. The function may have +different addresses within the executable and within the shared object. .It Fl -image-base Ns = Ns Ar value Set the base address to .Ar value . @@ -241,6 +256,11 @@ Set target emulation. .It Fl -Map Ns = Ns Ar file , Fl M Ar file Print a link map to .Ar file . +.It Fl -nmagic , Fl n +Do not page align sections, link against static libraries. +.It Fl -no-allow-shlib-undefined +Do not allow unresolved references in shared libraries. +This option is enabled by default when linking an executable. .It Fl -no-as-needed Always set .Dv DT_NEEDED @@ -259,6 +279,12 @@ section. Disable garbage collection of unused sections. .It Fl -no-gnu-unique Disable STB_GNU_UNIQUE symbol binding. +.It Fl -no-merge-exidx-entries +Disable merging .ARM.exidx entries. +.It Fl -no-nmagic +Page align sections. +.It Fl -no-omagic +Do not set the text data sections to be writable, page align sections. .It Fl -no-rosegment Do not put read-only non-executable sections in their own segment. .It Fl -no-threads @@ -267,9 +293,11 @@ Do not run the linker multi-threaded. Report version scripts that refer undefined symbols. .It Fl -no-undefined Report unresolved symbols even if the linker is creating a shared library. +.It Fl -no-warn-symbol-ordering +Do not warn about problems with the symbol ordering file or call graph profile. .It Fl -no-whole-archive Restores the default behavior of loading archive members. -.It Fl -no-pie +.It Fl -no-pie , Fl -no-pic-executable Do not create a position independent executable. .It Fl -noinhibit-exec Retain the executable output file whenever it is still usable. @@ -305,13 +333,62 @@ is .Cm binary , which produces output with no ELF header. .It Fl -omagic , Fl N -Set the text and data sections to be readable and writable. +Set the text and data sections to be readable and writable, do not page align sections, link against static libraries. .It Fl -opt-remarks-filename Ar file Write optimization remarks in YAML format to .Ar file . +.It Fl -opt-remarks-passes Ar pass-regex +Filter optimization remarks by only allowing the passes matching +.Ar pass-regex . .It Fl -opt-remarks-with-hotness Include hotness information in the optimization remarks file. -.It Fl -pie +.It Fl -orphan-handling Ns = Ns Ar mode +Control how orphan sections are handled. An orphan section is one not +specifically mentioned in a linker script. +.Ar mode +may be: +.Pp +.Bl -tag -width 2n -compact +.It Cm place +Place orphan sections in suitable output sections. +.It Cm warn +Place orphan sections as for +.Cm place +and also report a warning. +.It Cm error +Place orphan sections as for +.Cm place +and also report an error. +.El +.Pp +.Cm place +is the default. +.It Fl -pack-dyn-relocs Ns = Ns Ar format +Pack dynamic relocations in the given format. +.Ar format +may be: +.Pp +.Bl -tag -width 2n -compact +.It Cm none +Don't pack. Dynamic relocations are encoded in SHT_REL(A). +.It Cm android +Pack dynamic relocations in SHT_ANDROID_REL(A). +.It Cm relr +Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_REL(A). +.It Cm android+relr +Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in SHT_ANDROID_REL(A). +.El +.Pp +.Cm none +is the default. If +.Fl -use-android-relr-tags +is specified, use SHT_ANDROID_RELR instead of SHT_RELR. +.Pp +.It Fl -pac-plt +AArch64 only, use pointer authentication in PLT. +.It Fl -pic-veneer +Always generate position independent thunks. +.It Fl -pie , Fl -pic-executable Create a position independent executable. .It Fl -print-gc-sections List removed unused sections. @@ -356,6 +433,8 @@ Set .Dv DT_SONAME to .Ar value . +.It Fl -sort-common +This option is ignored for GNU compatibility. .It Fl -sort-section Ns = Ns Ar value Specifies sections sorting rule when linkerscript is used. .It Fl -start-lib @@ -425,11 +504,27 @@ Print the names of the input files. Trace references to .Ar symbol . .It Fl -undefined Ns = Ns Ar symbol , Fl u Ar symbol -Force +If .Ar symbol -to be an undefined symbol during linking. +is not defined after symbol resolution, and there's a static library +that contains an object file defining the symbol, load the member +to include the object file in the output file. +.It Fl -undefined-glob Ns = Ns Ar pattern +Synonym for +.Fl -undefined , +except that it takes a glob pattern. In a glob pattern, +.Cm * +matches zero or more characters, +.Cm ? +matches any single character, and +.Cm [...] +matches the characters within brackets. All symbols that match +a given pattern are handled as if they were given as arguments of +.Fl -undefined . .It Fl -unresolved-symbols Ns = Ns Ar value Determine how to handle unresolved symbols. +.It Fl -use-android-relr-tags +Use SHT_ANDROID_RELR / DT_ANDROID_RELR* tags instead of SHT_RELR / DT_RELR*. .It Fl v Display the version number and proceed with linking if object files are specified. @@ -477,6 +572,14 @@ Sets the .Dv DYNAMIC section. Different loaders can decide how to handle this flag on their own. +.It Cm ifunc-noplt +Do not emit PLT entries for ifunc symbols. +Instead, emit text relocations referencing the resolver. +This is an experimental optimization and only suitable for standalone +environments where text relocations do not have the usual drawbacks. +This option must be combined with the +.Fl z Li notext +option. .It Cm initfirst Sets the .Dv DF_1_INITFIRST diff --git a/docs/missingkeyfunction.rst b/docs/missingkeyfunction.rst index 410c749c3b03..db4ea11b4a4f 100644 --- a/docs/missingkeyfunction.rst +++ b/docs/missingkeyfunction.rst @@ -1,26 +1,27 @@ -Missing Key Method -================== +Missing Key Function +==================== If your build failed with a linker error something like this:: foo.cc:28: error: undefined reference to 'vtable for C' - the vtable symbol may be undefined because the class is missing its key function (see https://lld.llvm.org/missingkeyfunction) + the vtable symbol may be undefined because the class is missing its key function + (see https://lld.llvm.org/missingkeyfunction) it's likely that your class C has a key function (defined by the ABI as the first -non-pure, non-inline, virtual method), but you haven't actually defined it. +non-pure, non-inline, virtual function), but you haven't actually defined it. When a class has a key function, the compiler emits the vtable (and some other things as well) only in the translation unit that defines that key function. Thus, if you're missing the key function, you'll also be missing the vtable. If no other -function calls your missing method, you won't see any undefined reference errors +function calls your missing function, you won't see any undefined reference errors for it, but you will see undefined references to the vtable symbol. -When a class has no non-pure, non-inline, virtual methods, there is no key -method, and the compiler is forced to emit the vtable in every translation unit +When a class has no non-pure, non-inline, virtual functions, there is no key +function, and the compiler is forced to emit the vtable in every translation unit that references the class. In this case, it is emitted in a COMDAT section, which allows the linker to eliminate all duplicate copies. This is still wasteful in terms of object file size and link time, so it's always advisable to -ensure there is at least one eligible method that can serve as the key function. +ensure there is at least one eligible function that can serve as the key function. Here are the most common mistakes that lead to this error: @@ -36,8 +37,8 @@ Say you have a base class declared in a header file:: ... }; -Here, ``~B`` is the first non-pure, non-inline, virtual method, so it is the key -method. If you forget to define ``B::~B`` in your source file, the compiler will +Here, ``~B`` is the first non-pure, non-inline, virtual function, so it is the key +function. If you forget to define ``B::~B`` in your source file, the compiler will not emit the vtable for ``B``, and you'll get an undefined reference to "vtable for B". @@ -47,10 +48,10 @@ the first eligible key function and it's easy to forget to implement them. It's also more likely that you won't have any direct references to the destructor, so you won't see any undefined reference errors that point directly to the problem. -The solution in this case is to implement the missing method. +The solution in this case is to implement the missing function. -Forgetting to declare a virtual method in an abstract class as pure -------------------------------------------------------------------- +Forgetting to declare a virtual function in an abstract class as pure +--------------------------------------------------------------------- Say you have an abstract base class declared in a header file:: @@ -65,18 +66,18 @@ Say you have an abstract base class declared in a header file:: }; This base class is intended to be abstract, but you forgot to mark one of the -methods pure. Here, ``A::bar``, being non-pure, is nominated as the key function, +functions pure. Here, ``A::bar``, being non-pure, is nominated as the key function, and as a result, the vtable for ``A`` is not emitted, because the compiler is waiting for a translation unit that defines ``A::bar``. The solution in this case is to add the missing ``= 0`` to the declaration of ``A::bar``. -Key method is defined, but the linker doesn't see it ----------------------------------------------------- +Key function is defined, but the linker doesn't see it +------------------------------------------------------ It's also possible that you have defined the key function somewhere, but the -object file containing the definition of that method isn't being linked into +object file containing the definition of that function isn't being linked into your application. The solution in this case is to check your dependencies to make sure that diff --git a/docs/partitions.dot b/docs/partitions.dot new file mode 100644 index 000000000000..81f12a2f4283 --- /dev/null +++ b/docs/partitions.dot @@ -0,0 +1,22 @@ +digraph G { + part_main [label="Main partition",shape=plaintext]; + part1 [label="Loadable partition 1",shape=plaintext]; + part2 [label="Loadable partition 2",shape=plaintext]; + main [style=filled,fillcolor=lightblue]; + f1 [style=filled,fillcolor=lightsalmon]; + f2 [style=filled,fillcolor=palegreen]; + f3 [style=filled,fillcolor=lightblue]; + f4 [style=filled,fillcolor=lightsalmon]; + f5 [style=filled,fillcolor=lightblue]; + f6 [style=filled,fillcolor=palegreen]; + part_main -> main; + main -> f3; + part1 -> f1; + f1 -> f3; + f1 -> f4; + f1 -> f5; + part2 -> f2; + f2 -> f3; + f2 -> f5; + f2 -> f6; +} diff --git a/docs/partitions.svg b/docs/partitions.svg new file mode 100644 index 000000000000..39cd96933446 --- /dev/null +++ b/docs/partitions.svg @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" + "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<!-- Generated by graphviz version 2.38.0 (20140413.2041) + --> +<!-- Title: G Pages: 1 --> +<svg width="393pt" height="188pt" + viewBox="0.00 0.00 393.00 188.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)"> +<title>G</title> +<polygon fill="white" stroke="none" points="-4,4 -4,-184 389,-184 389,4 -4,4"/> +<!-- part_main --> +<g id="node1" class="node"><title>part_main</title> +<text text-anchor="middle" x="47.5" y="-158.3" font-family="Times,serif" font-size="14.00">Main partition</text> +</g> +<!-- main --> +<g id="node4" class="node"><title>main</title> +<ellipse fill="lightblue" stroke="black" cx="75.5" cy="-90" rx="28.6953" ry="18"/> +<text text-anchor="middle" x="75.5" y="-86.3" font-family="Times,serif" font-size="14.00">main</text> +</g> +<!-- part_main->main --> +<g id="edge1" class="edge"><title>part_main->main</title> +<path fill="none" stroke="black" d="M54.4214,-143.697C57.6218,-135.696 61.492,-126.02 65.0381,-117.155"/> +<polygon fill="black" stroke="black" points="68.3868,-118.207 68.8511,-107.622 61.8874,-115.607 68.3868,-118.207"/> +</g> +<!-- part1 --> +<g id="node2" class="node"><title>part1</title> +<text text-anchor="middle" x="176.5" y="-158.3" font-family="Times,serif" font-size="14.00">Loadable partition 1</text> +</g> +<!-- f1 --> +<g id="node5" class="node"><title>f1</title> +<ellipse fill="lightsalmon" stroke="black" cx="176.5" cy="-90" rx="27" ry="18"/> +<text text-anchor="middle" x="176.5" y="-86.3" font-family="Times,serif" font-size="14.00">f1</text> +</g> +<!-- part1->f1 --> +<g id="edge3" class="edge"><title>part1->f1</title> +<path fill="none" stroke="black" d="M176.5,-143.697C176.5,-135.983 176.5,-126.712 176.5,-118.112"/> +<polygon fill="black" stroke="black" points="180,-118.104 176.5,-108.104 173,-118.104 180,-118.104"/> +</g> +<!-- part2 --> +<g id="node3" class="node"><title>part2</title> +<text text-anchor="middle" x="321.5" y="-158.3" font-family="Times,serif" font-size="14.00">Loadable partition 2</text> +</g> +<!-- f2 --> +<g id="node6" class="node"><title>f2</title> +<ellipse fill="palegreen" stroke="black" cx="284.5" cy="-90" rx="27" ry="18"/> +<text text-anchor="middle" x="284.5" y="-86.3" font-family="Times,serif" font-size="14.00">f2</text> +</g> +<!-- part2->f2 --> +<g id="edge7" class="edge"><title>part2->f2</title> +<path fill="none" stroke="black" d="M312.354,-143.697C307.97,-135.403 302.636,-125.311 297.813,-116.187"/> +<polygon fill="black" stroke="black" points="300.801,-114.35 293.034,-107.145 294.612,-117.621 300.801,-114.35"/> +</g> +<!-- f3 --> +<g id="node7" class="node"><title>f3</title> +<ellipse fill="lightblue" stroke="black" cx="104.5" cy="-18" rx="27" ry="18"/> +<text text-anchor="middle" x="104.5" y="-14.3" font-family="Times,serif" font-size="14.00">f3</text> +</g> +<!-- main->f3 --> +<g id="edge2" class="edge"><title>main->f3</title> +<path fill="none" stroke="black" d="M82.3726,-72.411C85.7675,-64.2164 89.9422,-54.1395 93.7473,-44.9548"/> +<polygon fill="black" stroke="black" points="97.0828,-46.0481 97.6767,-35.4699 90.6158,-43.3689 97.0828,-46.0481"/> +</g> +<!-- f1->f3 --> +<g id="edge4" class="edge"><title>f1->f3</title> +<path fill="none" stroke="black" d="M161.93,-74.8345C151.75,-64.9376 137.976,-51.5462 126.469,-40.3591"/> +<polygon fill="black" stroke="black" points="128.905,-37.8461 119.296,-33.3847 124.026,-42.865 128.905,-37.8461"/> +</g> +<!-- f4 --> +<g id="node8" class="node"><title>f4</title> +<ellipse fill="lightsalmon" stroke="black" cx="176.5" cy="-18" rx="27" ry="18"/> +<text text-anchor="middle" x="176.5" y="-14.3" font-family="Times,serif" font-size="14.00">f4</text> +</g> +<!-- f1->f4 --> +<g id="edge5" class="edge"><title>f1->f4</title> +<path fill="none" stroke="black" d="M176.5,-71.6966C176.5,-63.9827 176.5,-54.7125 176.5,-46.1124"/> +<polygon fill="black" stroke="black" points="180,-46.1043 176.5,-36.1043 173,-46.1044 180,-46.1043"/> +</g> +<!-- f5 --> +<g id="node9" class="node"><title>f5</title> +<ellipse fill="lightblue" stroke="black" cx="248.5" cy="-18" rx="27" ry="18"/> +<text text-anchor="middle" x="248.5" y="-14.3" font-family="Times,serif" font-size="14.00">f5</text> +</g> +<!-- f1->f5 --> +<g id="edge6" class="edge"><title>f1->f5</title> +<path fill="none" stroke="black" d="M191.07,-74.8345C201.25,-64.9376 215.024,-51.5462 226.531,-40.3591"/> +<polygon fill="black" stroke="black" points="228.974,-42.865 233.704,-33.3847 224.095,-37.8461 228.974,-42.865"/> +</g> +<!-- f2->f3 --> +<g id="edge8" class="edge"><title>f2->f3</title> +<path fill="none" stroke="black" d="M260.806,-81.0022C232.063,-71.1346 182.266,-53.5073 140.5,-36 138.683,-35.2385 136.825,-34.4358 134.957,-33.6106"/> +<polygon fill="black" stroke="black" points="136.231,-30.3452 125.68,-29.3829 133.328,-36.7149 136.231,-30.3452"/> +</g> +<!-- f2->f5 --> +<g id="edge9" class="edge"><title>f2->f5</title> +<path fill="none" stroke="black" d="M276.15,-72.7646C271.788,-64.2831 266.353,-53.7144 261.459,-44.1974"/> +<polygon fill="black" stroke="black" points="264.49,-42.4395 256.804,-35.1473 258.265,-45.6409 264.49,-42.4395"/> +</g> +<!-- f6 --> +<g id="node10" class="node"><title>f6</title> +<ellipse fill="palegreen" stroke="black" cx="320.5" cy="-18" rx="27" ry="18"/> +<text text-anchor="middle" x="320.5" y="-14.3" font-family="Times,serif" font-size="14.00">f6</text> +</g> +<!-- f2->f6 --> +<g id="edge10" class="edge"><title>f2->f6</title> +<path fill="none" stroke="black" d="M292.85,-72.7646C297.212,-64.2831 302.647,-53.7144 307.541,-44.1974"/> +<polygon fill="black" stroke="black" points="310.735,-45.6409 312.196,-35.1473 304.51,-42.4395 310.735,-45.6409"/> +</g> +</g> +</svg> diff --git a/docs/sphinx_intro.rst b/docs/sphinx_intro.rst index 6bb9816b5ab4..b671cdc3df64 100644 --- a/docs/sphinx_intro.rst +++ b/docs/sphinx_intro.rst @@ -43,8 +43,8 @@ to install it using: Use your distribution's standard package management tool to install it, i.e., ``apt-get install easy_install`` or ``yum install easy_install``. - Mac OS X - All modern Mac OS X systems come with ``easy_install`` as part of the base + macOS + All modern macOS systems come with ``easy_install`` as part of the base system. Windows |
