1=============================== 2Assembling a Complete Toolchain 3=============================== 4 5.. contents:: 6 :local: 7 :depth: 2 8 9Introduction 10============ 11 12Clang is only one component in a complete tool chain for C family 13programming languages. In order to assemble a complete toolchain, 14additional tools and runtime libraries are required. Clang is designed 15to interoperate with existing tools and libraries for its target 16platforms, and the LLVM project provides alternatives for a number 17of these components. 18 19This document describes the required and optional components in a 20complete toolchain, where to find them, and the supported versions 21and limitations of each option. 22 23.. warning:: 24 25 This document currently describes Clang configurations on POSIX-like 26 operating systems with the GCC-compatible ``clang`` driver. When 27 targeting Windows with the MSVC-compatible ``clang-cl`` driver, some 28 of the details are different. 29 30Tools 31===== 32 33.. FIXME: Describe DWARF-related tools 34 35A complete compilation of C family programming languages typically 36involves the following pipeline of tools, some of which are omitted 37in 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 and 44 builds a source-level intermediate representation ("AST"), producing a 45 :ref:`precompiled header (PCH) <usersmanual-precompiled-headers>`, 46 preamble, or 47 :doc:`precompiled module file (PCM) <Modules>`, 48 depending on the input. 49 The ``-precompile`` flag instructs Clang to stop after this step. This is 50 the default when the input is a header file. 51 52* **IR generation**: This converts the source-level intermediate representation 53 into an optimizer-specific intermediate representation (IR); for Clang, this 54 is LLVM IR. 55 The ``-emit-llvm`` flag instructs Clang to stop after this step. If combined 56 with ``-S``, Clang will produce textual LLVM IR; otherwise, it will produce 57 LLVM IR bitcode. 58 59* **Compiler backend**: This converts the intermediate representation 60 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 into 64 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 image 68 (either a shared object or an executable). 69 70Clang provides all of these pieces other than the linker. When multiple 71steps are performed by the same tool, it is common for the steps to be 72fused together to avoid creating intermediate files. 73 74When given an output of one of the above steps as an input, earlier steps 75are 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 need 78to be escaped under most shells) to see which commands it would run for the 79above steps, without running them. The ``-v`` (verbose) flag will print the 80commands in addition to running them. 81 82Clang frontend 83-------------- 84 85The Clang frontend (``clang -cc1``) is used to compile C family languages. The 86command-line interface of the frontend is considered to be an implementation 87detail, intentionally has no external documentation, and is subject to change 88without notice. 89 90Language frontends for other languages 91-------------------------------------- 92 93Clang can be provided with inputs written in non-C-family languages. In such 94cases, an external tool will be used to compile the input. The 95currently-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 103Assember 104-------- 105 106Clang can either use LLVM's integrated assembler or an external system-specific 107tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from 108assembly. 109By default, Clang uses LLVM's integrated assembler on all targets where it is 110supported. If you wish to use the system assember instead, use the 111``-fno-integrated-as`` option. 112 113Linker 114------ 115 116Clang can be configured to use one of several different linkers: 117 118* GNU ld 119* GNU gold 120* LLVM's `lld <http://lld.llvm.org>`_ 121* MSVC's link.exe 122 123Link-time optimization is natively supported by lld, and supported via 124a `linker plugin <http://llvm.org/docs/GoldPlugin.html>`_ when using gold. 125 126The default linker varies between targets, and can be overridden via the 127``-fuse-ld=<linker name>`` flag. 128 129Runtime libraries 130================= 131 132A number of different runtime libraries are required to provide different 133layers of support for C family programs. Clang will implicitly link an 134appropriate implementation of each runtime library, selected based on 135target defaults or explicitly selected by the ``--rtlib=`` and ``--stdlib=`` 136flags. 137 138The set of implicitly-linked libraries depend on the language mode. As a 139consequence, you should use ``clang++`` when linking C++ programs in order 140to ensure the C++ runtimes are provided. 141 142.. note:: 143 144 There may exist other implementations for these components not described 145 below. Please let us know how well those other implementations work with 146 Clang so they can be added to this list! 147 148.. FIXME: Describe Objective-C runtime libraries 149.. FIXME: Describe profiling runtime library 150.. FIXME: Describe cuda/openmp/opencl/... runtime libraries 151 152Compiler runtime 153---------------- 154 155The compiler runtime library provides definitions of functions implicitly 156invoked by the compiler to support operations not natively supported by 157the 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 is 161the dominant compiler, Clang currently defaults to using libgcc_s. On most 162other targets, compiler-rt is used by default. 163 164compiler-rt (LLVM) 165^^^^^^^^^^^^^^^^^^ 166 167`LLVM's compiler runtime library <http://compiler-rt.llvm.org/>`_ provides a 168complete set of runtime library functions containing all functions that 169Clang 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 use 175compiler-rt rather than libgcc_s by passing ``-DLIBCXX_USE_COMPILER_RT=YES`` 176and/or ``-DLIBCXXABI_USE_COMPILER_RT=YES`` to ``cmake``. Otherwise, you 177may end up with both runtime libraries linked into your program (this is 178typically 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 functions 185that LLVM may emit references to, particularly when using Clang's 186``__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 library 192--------------- 193 194If your program makes use of atomic operations and the compiler is not able 195to lower them all directly to machine instructions (because there either is 196no known suitable machine instruction or the operand is not known to be 197suitably aligned), a call to a runtime library ``__atomic_*`` function 198will be generated. A runtime library containing these atomics functions is 199necessary 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 be 211used to supply these when using libgcc_s. 212 213.. note:: 214 215 Clang does not currently automatically link against libatomic when using 216 libgcc_s. You may need to manually add ``-latomic`` to support this 217 configuration when using non-native atomic operations (if you see link errors 218 referring to ``__atomic_*`` functions). 219 220Unwind library 221-------------- 222 223The unwind library provides a family of ``_Unwind_*`` functions implementing 224the language-neutral stack unwinding portion of the Itanium C++ ABI 225(`Level I <http://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 dependency 227of other runtimes. 228 229libunwind (LLVM) 230^^^^^^^^^^^^^^^^ 231 232LLVM's unwinder library can be obtained from subversion: 233 234.. code-block:: console 235 236 llvm-src$ svn co http://llvm.org/svn/llvm-project/libunwind/trunk projects/libunwind 237 238When checked out into projects/libunwind within an LLVM checkout, 239it should be automatically picked up by the LLVM build system. 240 241If using libc++abi, you may need to configure it to use libunwind 242rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES`` 243to ``cmake``. If libc++abi is configured to use some version of 244libunwind, that library will be implicitly linked into binaries that 245link to libc++abi. 246 247libgcc_s (GNU) 248^^^^^^^^^^^^^^ 249 250libgcc_s has an integrated unwinder, and does not need an external unwind 251library to be provided. 252 253libunwind (nongnu.org) 254^^^^^^^^^^^^^^^^^^^^^^ 255 256This is another implementation of the libunwind specification. 257See `libunwind (nongnu.org) <http://www.nongnu.org/libunwind>`_. 258 259libunwind (PathScale) 260^^^^^^^^^^^^^^^^^^^^^ 261 262This is another implementation of the libunwind specification. 263See `libunwind (pathscale) <https://github.com/pathscale/libunwind>`_. 264 265Sanitizer runtime 266----------------- 267 268The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly 269makes calls to a runtime library, in order to maintain side state about the 270execution of the program and to issue diagnostic messages when a problem is 271detected. 272 273The only supported implementation of these runtimes is provided by LLVM's 274compiler-rt, and the relevant portion of that library 275(``libclang_rt.<sanitizer>.<arch>.a``) 276will be implicitly linked when linking with a ``-fsanitize=...`` flag. 277 278C standard library 279------------------ 280 281Clang supports a wide variety of 282`C standard library <http://en.cppreference.com/w/c>`_ 283implementations. 284 285C++ ABI library 286--------------- 287 288The C++ ABI library provides an implementation of the library portion of 289the Itanium C++ ABI, covering both the 290`support functionality in the main Itanium C++ ABI document 291<http://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and 292`Level II of the exception handling support 293<http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi>`_. 294References to the functions and objects in this library are implicitly 295generated by Clang when compiling C++ code. 296 297While it is possible to link C++ code using libstdc++ and code using libc++ 298together into the same program (so long as you do not attempt to pass C++ 299standard library objects across the boundary), it is not generally possible 300to have more than one C++ ABI library in a program. 301 302The version of the C++ ABI library used by Clang will be the one that the 303chosen C++ standard library was linked against. Several implementations are 304available: 305 306libc++abi (LLVM) 307^^^^^^^^^^^^^^^^ 308 309`libc++abi <http://libcxxabi.llvm.org/>`_ is LLVM's implementation of this 310specification. 311 312libsupc++ (GNU) 313^^^^^^^^^^^^^^^ 314 315libsupc++ is GCC's implementation of this specification. However, this 316library is only used when libstdc++ is linked statically. The dynamic 317library version of libstdc++ contains a copy of libsupc++. 318 319.. note:: 320 321 Clang does not currently automatically link against libatomic when statically 322 linking libstdc++. You may need to manually add ``-lsupc++`` to support this 323 configuration when using ``-static`` or ``-static-libstdc++``. 324 325libcxxrt (PathScale) 326^^^^^^^^^^^^^^^^^^^^ 327 328This is another implementation of the Itanium C++ ABI specification. 329See `libcxxrt <https://github.com/pathscale/libcxxrt>`_. 330 331C++ standard library 332-------------------- 333 334Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation 335of the `C++ standard library <http://en.cppreference.com/w/cpp>`_. 336 337libc++ (LLVM) 338^^^^^^^^^^^^^ 339 340`libc++ <http://libcxx.llvm.org/>`_ is LLVM's implementation of the C++ 341standard library, aimed at being a complete implementation of the C++ 342standards from C++11 onwards. 343 344You can instruct Clang to use libc++ with the ``-stdlib=libc++`` flag. 345 346libstdc++ (GNU) 347^^^^^^^^^^^^^^^ 348 349`libstdc++ <https://gcc.gnu.org/onlinedocs/libstdc++/>`_ is GCC's implementation 350of the C++ standard library. Clang supports a wide range of versions of 351libstdc++, from around version 4.2 onwards, and will implicitly work around 352some bugs in older versions of libstdc++. 353 354You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag. 355