355 lines · plain
1===============================2Assembling a Complete Toolchain3===============================4 5.. contents::6 :local:7 :depth: 28 9Introduction10============11 12Clang is only one component in a complete tool chain for C family13programming languages. In order to assemble a complete toolchain,14additional tools and runtime libraries are required. Clang is designed15to interoperate with existing tools and libraries for its target16platforms, and the LLVM project provides alternatives for a number17of these components.18 19This document describes the required and optional components in a20complete toolchain, where to find them, and the supported versions21and limitations of each option.22 23.. warning::24 25 This document currently describes Clang configurations on POSIX-like26 operating systems with the GCC-compatible ``clang`` driver. When27 targeting Windows with the MSVC-compatible ``clang-cl`` driver, some28 of the details are different.29 30Tools31=====32 33.. FIXME: Describe DWARF-related tools34 35A complete compilation of C family programming languages typically36involves the following pipeline of tools, some of which are omitted37in some compilations:38 39* **Preprocessor**: This performs the actions of the C preprocessor:40 expanding #includes and #defines.41 The ``-E`` flag instructs Clang to stop after this step.42 43* **Parsing**: This parses and semantically analyzes the source language and44 builds a source-level intermediate representation ("AST"), producing a45 :ref:`precompiled header (PCH) <usersmanual-precompiled-headers>`,46 preamble, or47 :doc:`precompiled module file (PCM) <Modules>`,48 depending on the input.49 The ``-precompile`` flag instructs Clang to stop after this step. This is50 the default when the input is a header file.51 52* **IR generation**: This converts the source-level intermediate representation53 into an optimizer-specific intermediate representation (IR); for Clang, this54 is LLVM IR.55 The ``-emit-llvm`` flag instructs Clang to stop after this step. If combined56 with ``-S``, Clang will produce textual LLVM IR; otherwise, it will produce57 LLVM IR bitcode.58 59* **Compiler backend**: This converts the intermediate representation60 into target-specific assembly code.61 The ``-S`` flag instructs Clang to stop after this step.62 63* **Assembler**: This converts target-specific assembly code into64 target-specific machine code object files.65 The ``-c`` flag instructs Clang to stop after this step.66 67* **Linker**: This combines multiple object files into a single image68 (either a shared object or an executable).69 70Clang provides all of these pieces other than the linker. When multiple71steps are performed by the same tool, it is common for the steps to be72fused together to avoid creating intermediate files.73 74When given an output of one of the above steps as an input, earlier steps75are skipped (for instance, a ``.s`` file input will be assembled and linked).76 77The Clang driver can be invoked with the ``-###`` flag (this argument will need78to be escaped under most shells) to see which commands it would run for the79above steps, without running them. The ``-v`` (verbose) flag will print the80commands in addition to running them.81 82Clang frontend83--------------84 85The Clang frontend (``clang -cc1``) is used to compile C family languages. The86command-line interface of the frontend is considered to be an implementation87detail, intentionally has no external documentation, and is subject to change88without notice.89 90Language frontends for other languages91--------------------------------------92 93Clang can be provided with inputs written in non-C-family languages. In such94cases, an external tool will be used to compile the input. The95currently-supported languages are:96 97* Ada (``-x ada``, ``.ad[bs]``)98* Fortran (``-x f95``, ``.f``, ``.f9[05]``, ``.for``, ``.fpp``, case-insensitive)99* Java (``-x java``)100 101In each case, GCC will be invoked to compile the input.102 103Assembler104---------105 106Clang can either use LLVM's integrated assembler or an external system-specific107tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from108assembly.109By default, Clang uses LLVM's integrated assembler on all targets where it is110supported. If you wish to use the system assembler instead, use the111``-fno-integrated-as`` option.112 113Linker114------115 116Clang can be configured to use one of several different linkers:117 118* GNU ld119* GNU gold120* LLVM's `lld <https://lld.llvm.org>`_121* MSVC's link.exe122 123Link-time optimization is natively supported by lld, and supported via124a `linker plugin <https://llvm.org/docs/GoldPlugin.html>`_ when using gold.125 126The default linker varies between targets, and can be overridden via the127``-fuse-ld=<linker name>`` flag.128 129Runtime libraries130=================131 132A number of different runtime libraries are required to provide different133layers of support for C family programs. Clang will implicitly link an134appropriate implementation of each runtime library, selected based on135target defaults or explicitly selected by the ``--rtlib=`` and ``--stdlib=``136flags.137 138The set of implicitly-linked libraries depend on the language mode. As a139consequence, you should use ``clang++`` when linking C++ programs in order140to ensure the C++ runtimes are provided.141 142.. note::143 144 There may exist other implementations for these components not described145 below. Please let us know how well those other implementations work with146 Clang so they can be added to this list!147 148.. FIXME: Describe Objective-C runtime libraries149.. FIXME: Describe profiling runtime library150.. FIXME: Describe cuda/openmp/opencl/... runtime libraries151 152Compiler runtime153----------------154 155The compiler runtime library provides definitions of functions implicitly156invoked by the compiler to support operations not natively supported by157the underlying hardware (for instance, 128-bit integer multiplications),158and where inline expansion of the operation is deemed unsuitable.159 160The default runtime library is target-specific. For targets where GCC is161the dominant compiler, Clang currently defaults to using libgcc_s. On most162other targets, compiler-rt is used by default.163 164compiler-rt (LLVM)165^^^^^^^^^^^^^^^^^^166 167`LLVM's compiler runtime library <https://compiler-rt.llvm.org/>`_ provides a168complete set of runtime library functions containing all functions that169Clang will implicitly call, in ``libclang_rt.builtins.<arch>.a``.170 171You can instruct Clang to use compiler-rt with the ``--rtlib=compiler-rt`` flag.172This is not supported on every platform.173 174If using libc++ and/or libc++abi, you may need to configure them to use175compiler-rt rather than libgcc_s by passing ``-DLIBCXX_USE_COMPILER_RT=YES``176and/or ``-DLIBCXXABI_USE_COMPILER_RT=YES`` to ``cmake``. Otherwise, you177may end up with both runtime libraries linked into your program (this is178typically harmless, but wasteful).179 180libgcc_s (GNU)181^^^^^^^^^^^^^^182 183`GCC's runtime library <https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html>`_184can be used in place of compiler-rt. However, it lacks several functions185that LLVM may emit references to, particularly when using Clang's186``__builtin_*_overflow`` family of intrinsics.187 188You can instruct Clang to use libgcc_s with the ``--rtlib=libgcc`` flag.189This is not supported on every platform.190 191Atomics library192---------------193 194If your program makes use of atomic operations and the compiler is not able195to lower them all directly to machine instructions (because there either is196no known suitable machine instruction or the operand is not known to be197suitably aligned), a call to a runtime library ``__atomic_*`` function198will be generated. A runtime library containing these atomics functions is199necessary for such programs.200 201compiler-rt (LLVM)202^^^^^^^^^^^^^^^^^^203 204compiler-rt contains an implementation of an atomics library.205 206libatomic (GNU)207^^^^^^^^^^^^^^^208 209libgcc_s does not provide an implementation of an atomics library. Instead,210`GCC's libatomic library <https://gcc.gnu.org/wiki/Atomic/GCCMM>`_ can be211used to supply these when using libgcc_s.212 213.. note::214 215 Clang does not currently automatically link against libatomic when using216 libgcc_s. You may need to manually add ``-latomic`` to support this217 configuration when using non-native atomic operations (if you see link errors218 referring to ``__atomic_*`` functions).219 220Unwind library221--------------222 223The unwind library provides a family of ``_Unwind_*`` functions implementing224the language-neutral stack unwinding portion of the Itanium C++ ABI225(`Level I <https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#base-abi>`_).226It is a dependency of the C++ ABI library, and sometimes is a dependency227of other runtimes.228 229libunwind (LLVM)230^^^^^^^^^^^^^^^^231 232LLVM's unwinder library is part of the llvm-project git repository. To233build it, pass ``-DLLVM_ENABLE_RUNTIMES=libunwind`` to the cmake invocation.234 235If using libc++abi, you may need to configure it to use libunwind236rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``237to ``cmake``. If libc++abi is configured to use some version of238libunwind, that library will be implicitly linked into binaries that239link to libc++abi.240 241libgcc_s (GNU)242^^^^^^^^^^^^^^243 244libgcc_s has an integrated unwinder, and does not need an external unwind245library to be provided.246 247libunwind (nongnu.org)248^^^^^^^^^^^^^^^^^^^^^^249 250This is another implementation of the libunwind specification.251See `libunwind (nongnu.org) <https://www.nongnu.org/libunwind>`_.252 253libunwind (PathScale)254^^^^^^^^^^^^^^^^^^^^^255 256This is another implementation of the libunwind specification.257See `libunwind (pathscale) <https://github.com/pathscale/libunwind>`_.258 259Sanitizer runtime260-----------------261 262The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly263makes calls to a runtime library, in order to maintain side state about the264execution of the program and to issue diagnostic messages when a problem is265detected.266 267The only supported implementation of these runtimes is provided by LLVM's268compiler-rt, and the relevant portion of that library269(``libclang_rt.<sanitizer>.<arch>.a``)270will be implicitly linked when linking with a ``-fsanitize=...`` flag.271 272C standard library273------------------274 275Clang supports a wide variety of276`C standard library <https://en.cppreference.com/w/c>`_277implementations.278 279C++ ABI library280---------------281 282The C++ ABI library provides an implementation of the library portion of283the Itanium C++ ABI, covering both the284`support functionality in the main Itanium C++ ABI document285<https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and286`Level II of the exception handling support287<https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi>`_.288References to the functions and objects in this library are implicitly289generated by Clang when compiling C++ code.290 291While it is possible to link C++ code using libstdc++ and code using libc++292together into the same program (so long as you do not attempt to pass C++293standard library objects across the boundary), it is not generally possible294to have more than one C++ ABI library in a program.295 296The version of the C++ ABI library used by Clang will be the one that the297chosen C++ standard library was linked against. Several implementations are298available:299 300libc++abi (LLVM)301^^^^^^^^^^^^^^^^302 303`libc++abi <https://libcxxabi.llvm.org/>`_ is LLVM's implementation of this304specification.305 306libsupc++ (GNU)307^^^^^^^^^^^^^^^308 309libsupc++ is GCC's implementation of this specification. However, this310library is only used when libstdc++ is linked statically. The dynamic311library version of libstdc++ contains a copy of libsupc++.312 313.. note::314 315 Clang does not currently automatically link against libsupc++ when statically316 linking libstdc++. You may need to manually add ``-lsupc++`` to support this317 configuration when using ``-static`` or ``-static-libstdc++``.318 319libcxxrt (PathScale)320^^^^^^^^^^^^^^^^^^^^321 322This is another implementation of the Itanium C++ ABI specification.323See `libcxxrt <https://github.com/pathscale/libcxxrt>`_.324 325C++ standard library326--------------------327 328Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation329of the `C++ standard library <https://en.cppreference.com/w/cpp>`_.330 331libc++ (LLVM)332^^^^^^^^^^^^^333 334`libc++ <https://libcxx.llvm.org/>`_ is LLVM's implementation of the C++335standard library, aimed at being a complete implementation of the C++336standards from C++11 onwards.337 338You can instruct Clang to use libc++ with the ``-stdlib=libc++`` flag.339 340libstdc++ (GNU)341^^^^^^^^^^^^^^^342 343`libstdc++ <https://gcc.gnu.org/onlinedocs/libstdc++/>`_ is GCC's344implementation of the C++ standard library. Clang supports libstdc++3454.8.3 (released 2014-05-22) and later. Historically Clang implemented346workarounds for issues discovered in libstdc++, and these are removed347as fixed libstdc++ becomes sufficiently old.348 349You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag.350 351GCC Installation352=================353Users can point to their GCC installation by using the ``-gcc-toolchain`` or by354using ``-gcc-install-dir`` flag.355