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 103Assembler 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 assembler 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 <https://lld.llvm.org>`_ 121* MSVC's link.exe 122 123Link-time optimization is natively supported by lld, and supported via 124a `linker plugin <https://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 <https://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 <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 dependency 227of other runtimes. 228 229libunwind (LLVM) 230^^^^^^^^^^^^^^^^ 231 232LLVM's unwinder library is part of the llvm-project git repository. To 233build it, pass ``-DLLVM_ENABLE_RUNTIMES=libunwind`` to the cmake invocation. 234 235If using libc++abi, you may need to configure it to use libunwind 236rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES`` 237to ``cmake``. If libc++abi is configured to use some version of 238libunwind, that library will be implicitly linked into binaries that 239link to libc++abi. 240 241libgcc_s (GNU) 242^^^^^^^^^^^^^^ 243 244libgcc_s has an integrated unwinder, and does not need an external unwind 245library 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 runtime 260----------------- 261 262The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly 263makes calls to a runtime library, in order to maintain side state about the 264execution of the program and to issue diagnostic messages when a problem is 265detected. 266 267The only supported implementation of these runtimes is provided by LLVM's 268compiler-rt, and the relevant portion of that library 269(``libclang_rt.<sanitizer>.<arch>.a``) 270will be implicitly linked when linking with a ``-fsanitize=...`` flag. 271 272C standard library 273------------------ 274 275Clang supports a wide variety of 276`C standard library <https://en.cppreference.com/w/c>`_ 277implementations. 278 279C++ ABI library 280--------------- 281 282The C++ ABI library provides an implementation of the library portion of 283the Itanium C++ ABI, covering both the 284`support functionality in the main Itanium C++ ABI document 285<https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and 286`Level II of the exception handling support 287<https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi>`_. 288References to the functions and objects in this library are implicitly 289generated 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 possible 294to 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 the 297chosen C++ standard library was linked against. Several implementations are 298available: 299 300libc++abi (LLVM) 301^^^^^^^^^^^^^^^^ 302 303`libc++abi <https://libcxxabi.llvm.org/>`_ is LLVM's implementation of this 304specification. 305 306libsupc++ (GNU) 307^^^^^^^^^^^^^^^ 308 309libsupc++ is GCC's implementation of this specification. However, this 310library is only used when libstdc++ is linked statically. The dynamic 311library version of libstdc++ contains a copy of libsupc++. 312 313.. note:: 314 315 Clang does not currently automatically link against libsupc++ when statically 316 linking libstdc++. You may need to manually add ``-lsupc++`` to support this 317 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 library 326-------------------- 327 328Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation 329of 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's 344implementation of the C++ standard library. Clang supports libstdc++ 3454.8.3 (released 2014-05-22) and later. Historically Clang implemented 346workarounds for issues discovered in libstdc++, and these are removed 347as fixed libstdc++ becomes sufficiently old. 348 349You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag. 350