diff options
Diffstat (limited to 'docs/Toolchain.rst')
| -rw-r--r-- | docs/Toolchain.rst | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/docs/Toolchain.rst b/docs/Toolchain.rst new file mode 100644 index 000000000000..6ae8888c6936 --- /dev/null +++ b/docs/Toolchain.rst @@ -0,0 +1,354 @@ +=============================== +Assembling a Complete Toolchain +=============================== + +.. contents:: + :local: + :depth: 2 + +Introduction +============ + +Clang is only one component in a complete tool chain for C family +programming languages. In order to assemble a complete toolchain, +additional tools and runtime libraries are required. Clang is designed +to interoperate with existing tools and libraries for its target +platforms, and the LLVM project provides alternatives for a number +of these components. + +This document describes the required and optional components in a +complete toolchain, where to find them, and the supported versions +and limitations of each option. + +.. warning:: + + This document currently describes Clang configurations on POSIX-like + operating systems with the GCC-compatible ``clang`` driver. When + targeting Windows with the MSVC-compatible ``clang-cl`` driver, some + of the details are different. + +Tools +===== + +.. FIXME: Describe DWARF-related tools + +A complete compilation of C family programming languages typically +involves the following pipeline of tools, some of which are omitted +in some compilations: + +* **Preprocessor**: This performs the actions of the C preprocessor: + expanding #includes and #defines. + The ``-E`` flag instructs Clang to stop after this step. + +* **Parsing**: This parses and semantically analyzes the source language and + builds a source-level intermediate representation ("AST"), producing a + :ref:`precompiled header (PCH) <usersmanual-precompiled-headers>`, + preamble, or + :doc:`precompiled module file (PCM) <Modules>`, + depending on the input. + The ``-precompile`` flag instructs Clang to stop after this step. This is + the default when the input is a header file. + +* **IR generation**: This converts the source-level intermediate representation + into an optimizer-specific intermediate representation (IR); for Clang, this + is LLVM IR. + The ``-emit-llvm`` flag instructs Clang to stop after this step. If combined + with ``-S``, Clang will produce textual LLVM IR; otherwise, it will produce + LLVM IR bitcode. + +* **Compiler backend**: This converts the intermediate representation + into target-specific assembly code. + The ``-S`` flag instructs Clang to stop after this step. + +* **Assembler**: This converts target-specific assembly code into + target-specific machine code object files. + The ``-c`` flag instructs Clang to stop after this step. + +* **Linker**: This combines multiple object files into a single image + (either a shared object or an executable). + +Clang provides all of these pieces other than the linker. When multiple +steps are performed by the same tool, it is common for the steps to be +fused together to avoid creating intermediate files. + +When given an output of one of the above steps as an input, earlier steps +are skipped (for instance, a ``.s`` file input will be assembled and linked). + +The Clang driver can be invoked with the ``-###`` flag (this argument will need +to be escaped under most shells) to see which commands it would run for the +above steps, without running them. The ``-v`` (verbose) flag will print the +commands in addition to running them. + +Clang frontend +-------------- + +The Clang frontend (``clang -cc1``) is used to compile C family languages. The +command-line interface of the frontend is considered to be an implementation +detail, intentionally has no external documentation, and is subject to change +without notice. + +Language frontends for other languages +-------------------------------------- + +Clang can be provided with inputs written in non-C-family languages. In such +cases, an external tool will be used to compile the input. The +currently-supported languages are: + +* Ada (``-x ada``, ``.ad[bs]``) +* Fortran (``-x f95``, ``.f``, ``.f9[05]``, ``.for``, ``.fpp``, case-insensitive) +* Java (``-x java``) + +In each case, GCC will be invoked to compile the input. + +Assember +-------- + +Clang can either use LLVM's integrated assembler or an external system-specific +tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from +assembly. +By default, Clang uses LLVM's integrataed assembler on all targets where it is +supported. If you wish to use the system assember instead, use the +``-fno-integrated-as`` option. + +Linker +------ + +Clang can be configured to use one of several different linkers: + +* GNU ld +* GNU gold +* LLVM's `lld <http://lld.llvm.org>`_ +* MSVC's link.exe + +Link-time optimization is natively supported by lld, and supported via +a `linker plugin <http://llvm.org/docs/GoldPlugin.html>`_ when using gold. + +The default linker varies between targets, and can be overridden via the +``-fuse-ld=<linker name>`` flag. + +Runtime libraries +================= + +A number of different runtime libraries are required to provide different +layers of support for C family programs. Clang will implicitly link an +appropriate implementation of each runtime library, selected based on +target defaults or explicitly selected by the ``--rtlib=`` and ``--stdlib=`` +flags. + +The set of implicitly-linked libraries depend on the language mode. As a +consequence, you should use ``clang++`` when linking C++ programs in order +to ensure the C++ runtimes are provided. + +.. note:: + + There may exist other implementations for these components not described + below. Please let us know how well those other implementations work with + Clang so they can be added to this list! + +.. FIXME: Describe Objective-C runtime libraries +.. FIXME: Describe profiling runtime library +.. FIXME: Describe cuda/openmp/opencl/... runtime libraries + +Compiler runtime +---------------- + +The compiler runtime library provides definitions of functions implicitly +invoked by the compiler to support operations not natively supported by +the underlying hardware (for instance, 128-bit integer multiplications), +and where inline expansion of the operation is deemed unsuitable. + +The default runtime library is target-specific. For targets where GCC is +the dominant compiler, Clang currently defaults to using libgcc_s. On most +other targets, compiler-rt is used by default. + +compiler-rt (LLVM) +^^^^^^^^^^^^^^^^^^ + +`LLVM's compiler runtime library <http://compiler-rt.llvm.org/>`_ provides a +complete set of runtime library functions containing all functions that +Clang will implicitly call, in ``libclang_rt.builtins.<arch>.a``. + +You can instruct Clang to use compiler-rt with the ``--rtlib=compiler-rt`` flag. +This is not supported on every platform. + +If using libc++ and/or libc++abi, you may need to configure them to use +compiler-rt rather than libgcc_s by passing ``-DLIBCXX_USE_COMPILER_RT=YES`` +and/or ``-DLIBCXXABI_USE_COMPILER_RT=YES`` to ``cmake``. Otherwise, you +may end up with both runtime libraries linked into your program (this is +typically harmless, but wasteful). + +libgcc_s (GNU) +^^^^^^^^^^^^^^ + +`GCC's runtime library <https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html>`_ +can be used in place of compiler-rt. However, it lacks several functions +that LLVM may emit references to, particularly when using Clang's +``__builtin_*_overflow`` family of intrinsics. + +You can instruct Clang to use libgcc_s with the ``--rtlib=libgcc`` flag. +This is not supported on every platform. + +Atomics library +--------------- + +If your program makes use of atomic operations and the compiler is not able +to lower them all directly to machine instructions (because there either is +no known suitable machine instruction or the operand is not known to be +suitably aligned), a call to a runtime library ``__atomic_*`` function +will be generated. A runtime library containing these atomics functions is +necessary for such programs. + +compiler-rt (LLVM) +^^^^^^^^^^^^^^^^^^ + +compiler-rt contains an implementation of an atomics library. + +libatomic (GNU) +^^^^^^^^^^^^^^^ + +libgcc_s does not provide an implementation of an atomics library. Instead, +`GCC's libatomic library <https://gcc.gnu.org/wiki/Atomic/GCCMM>`_ can be +used to supply these when using libgcc_s. + +.. note:: + + Clang does not currently automatically link against libatomic when using + libgcc_s. You may need to manually add ``-latomic`` to support this + configuration when using non-native atomic operations (if you see link errors + referring to ``__atomic_*`` functions). + +Unwind library +-------------- + +The unwind library provides a family of ``_Unwind_*`` functions implementing +the language-neutral stack unwinding portion of the Itanium C++ ABI +(`Level I <http://mentorembedded.github.io/cxx-abi/abi-eh.html#base-abi>`_). +It is a dependency of the C++ ABI library, and sometimes is a dependency +of other runtimes. + +libunwind (LLVM) +^^^^^^^^^^^^^^^^ + +LLVM's unwinder library can be obtained from subversion: + +.. code-block:: console + + llvm-src$ svn co http://llvm.org/svn/llvm-project/libunwind/trunk projects/libunwind + +When checked out into projects/libunwind within an LLVM checkout, +it should be automatically picked up by the LLVM build system. + +If using libc++abi, you may need to configure it to use libunwind +rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES`` +to ``cmake``. If libc++abi is configured to use some version of +libunwind, that library will be implicitly linked into binaries that +link to libc++abi. + +libgcc_s (GNU) +^^^^^^^^^^^^^^ + +libgcc_s has an integrated unwinder, and does not need an external unwind +library to be provided. + +libunwind (nongnu.org) +^^^^^^^^^^^^^^^^^^^^^^ + +This is another implementation of the libunwind specification. +See `libunwind (nongnu.org) <http://www.nongnu.org/libunwind>`_. + +libunwind (PathScale) +^^^^^^^^^^^^^^^^^^^^^ + +This is another implementation of the libunwind specification. +See `libunwind (pathscale) <https://github.com/pathscale/libunwind>`_. + +Sanitizer runtime +----------------- + +The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly +makes calls to a runtime library, in order to maintain side state about the +execution of the program and to issue diagnostic messages when a problem is +detected. + +The only supported implementation of these runtimes is provided by LLVM's +compiler-rt, and the relevant portion of that library +(``libclang_rt.<sanitizer>.<arch>.a``) +will be implicitly linked when linking with a ``-fsanitize=...`` flag. + +C standard library +------------------ + +Clang supports a wide variety of +`C standard library <http://en.cppreference.com/w/c>`_ +implementations. + +C++ ABI library +--------------- + +The C++ ABI library provides an implementation of the library portion of +the Itanium C++ ABI, covering both the +`support functionality in the main Itanium C++ ABI document +<http://mentorembedded.github.io/cxx-abi/abi.html>`_ and +`Level II of the exception handling support +<http://mentorembedded.github.io/cxx-abi/abi-eh.html#cxx-abi>`_. +References to the functions and objects in this library are implicitly +generated by Clang when compiling C++ code. + +While it is possible to link C++ code using libstdc++ and code using libc++ +together into the same program (so long as you do not attempt to pass C++ +standard library objects across the boundary), it is not generally possible +to have more than one C++ ABI library in a program. + +The version of the C++ ABI library used by Clang will be the one that the +chosen C++ standard library was linked against. Several implementations are +available: + +libc++abi (LLVM) +^^^^^^^^^^^^^^^^ + +`libc++abi <http://libcxxabi.llvm.org/>`_ is LLVM's implementation of this +specification. + +libsupc++ (GNU) +^^^^^^^^^^^^^^^ + +libsupc++ is GCC's implementation of this specification. However, this +library is only used when libstdc++ is linked statically. The dynamic +library version of libstdc++ contains a copy of libsupc++. + +.. note:: + + Clang does not currently automatically link against libatomic when statically + linking libstdc++. You may need to manually add ``-lsupc++`` to support this + configuration when using ``-static`` or ``-static-libstdc++``. + +libcxxrt (PathScale) +^^^^^^^^^^^^^^^^^^^^ + +This is another implementation of the Itanium C++ ABI specification. +See `libcxxrt <https://github.com/pathscale/libcxxrt>`_. + +C++ standard library +-------------------- + +Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation +of the `C++ standard library <http://en.cppreference.com/w/cpp>`_. + +libc++ (LLVM) +^^^^^^^^^^^^^ + +`libc++ <http://libcxx.llvm.org/>`_ is LLVM's implementation of the C++ +standard library, aimed at being a complete implementation of the C++ +standards from C++11 onwards. + +You can instruct Clang to use libc++ with the ``-stdlib=libc++`` flag. + +libstdc++ (GNU) +^^^^^^^^^^^^^^^ + +`libstdc++ <https://gcc.gnu.org/onlinedocs/libstdc++/>`_ is GCC's implementation +of the C++ standard library. Clang supports a wide range of versions of +libstdc++, from around version 4.2 onwards, and will implicitly work around +some bugs in older versions of libstdc++. + +You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag. |