| =============================== |
| 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. |
| |
| Assembler |
| --------- |
| |
| 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 integrated assembler on all targets where it is |
| supported. If you wish to use the system assembler 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 <https://lld.llvm.org>`_ |
| * MSVC's link.exe |
| |
| Link-time optimization is natively supported by lld, and supported via |
| a `linker plugin <https://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 <https://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 <https://itanium-cxx-abi.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 is part of the llvm-project git repository. To |
| build it, pass ``-DLLVM_ENABLE_PROJECTS=libunwind`` to the cmake invocation. |
| |
| 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) <https://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 <https://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 |
| <https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and |
| `Level II of the exception handling support |
| <https://itanium-cxx-abi.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 <https://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 <https://en.cppreference.com/w/cpp>`_. |
| |
| libc++ (LLVM) |
| ^^^^^^^^^^^^^ |
| |
| `libc++ <https://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. |