clang/docs/Toolchain.rst

   1 ===============================
   2 Assembling a Complete Toolchain
   3 ===============================
   4
   5 .. contents::
   6    :local:
   7    :depth: 2
   8
   9 Introduction
  10 ============
  11
  12 Clang is only one component in a complete tool chain for C family
  13 programming languages. In order to assemble a complete toolchain,
  14 additional tools and runtime libraries are required. Clang is designed
  15 to interoperate with existing tools and libraries for its target
  16 platforms, and the LLVM project provides alternatives for a number
  17 of these components.
  18
  19 This document describes the required and optional components in a
  20 complete toolchain, where to find them, and the supported versions
  21 and 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
  30 Tools
  31 =====
  32
  33 .. FIXME: Describe DWARF-related tools
  34
  35 A complete compilation of C family programming languages typically
  36 involves the following pipeline of tools, some of which are omitted
  37 in 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
  70 Clang provides all of these pieces other than the linker. When multiple
  71 steps are performed by the same tool, it is common for the steps to be
  72 fused together to avoid creating intermediate files.
  73
  74 When given an output of one of the above steps as an input, earlier steps
  75 are skipped (for instance, a ``.s`` file input will be assembled and linked).
  76
  77 The Clang driver can be invoked with the ``-###`` flag (this argument will need
  78 to be escaped under most shells) to see which commands it would run for the
  79 above steps, without running them. The ``-v`` (verbose) flag will print the
  80 commands in addition to running them.
  81
  82 Clang frontend
  83 --------------
  84
  85 The Clang frontend (``clang -cc1``) is used to compile C family languages. The
  86 command-line interface of the frontend is considered to be an implementation
  87 detail, intentionally has no external documentation, and is subject to change
  88 without notice.
  89
  90 Language frontends for other languages
  91 --------------------------------------
  92
  93 Clang can be provided with inputs written in non-C-family languages. In such
  94 cases, an external tool will be used to compile the input. The
  95 currently-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
 101 In each case, GCC will be invoked to compile the input.
 102
 103 Assembler
 104 ---------
 105
 106 Clang can either use LLVM's integrated assembler or an external system-specific
 107 tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from
 108 assembly.
 109 By default, Clang uses LLVM's integrated assembler on all targets where it is
 110 supported. If you wish to use the system assembler instead, use the
 111 ``-fno-integrated-as`` option.
 112
 113 Linker
 114 ------
 115
 116 Clang 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
 123 Link-time optimization is natively supported by lld, and supported via
 124 a `linker plugin <https://llvm.org/docs/GoldPlugin.html>`_ when using gold.
 125
 126 The default linker varies between targets, and can be overridden via the
 127 ``-fuse-ld=<linker name>`` flag.
 128
 129 Runtime libraries
 130 =================
 131
 132 A number of different runtime libraries are required to provide different
 133 layers of support for C family programs. Clang will implicitly link an
 134 appropriate implementation of each runtime library, selected based on
 135 target defaults or explicitly selected by the ``--rtlib=`` and ``--stdlib=``
 136 flags.
 137
 138 The set of implicitly-linked libraries depend on the language mode. As a
 139 consequence, you should use ``clang++`` when linking C++ programs in order
 140 to 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
 152 Compiler runtime
 153 ----------------
 154
 155 The compiler runtime library provides definitions of functions implicitly
 156 invoked by the compiler to support operations not natively supported by
 157 the underlying hardware (for instance, 128-bit integer multiplications),
 158 and where inline expansion of the operation is deemed unsuitable.
 159
 160 The default runtime library is target-specific. For targets where GCC is
 161 the dominant compiler, Clang currently defaults to using libgcc_s. On most
 162 other targets, compiler-rt is used by default.
 163
 164 compiler-rt (LLVM)
 165 ^^^^^^^^^^^^^^^^^^
 166
 167 `LLVM's compiler runtime library <https://compiler-rt.llvm.org/>`_ provides a
 168 complete set of runtime library functions containing all functions that
 169 Clang will implicitly call, in ``libclang_rt.builtins.<arch>.a``.
 170
 171 You can instruct Clang to use compiler-rt with the ``--rtlib=compiler-rt`` flag.
 172 This is not supported on every platform.
 173
 174 If using libc++ and/or libc++abi, you may need to configure them to use
 175 compiler-rt rather than libgcc_s by passing ``-DLIBCXX_USE_COMPILER_RT=YES``
 176 and/or ``-DLIBCXXABI_USE_COMPILER_RT=YES`` to ``cmake``. Otherwise, you
 177 may end up with both runtime libraries linked into your program (this is
 178 typically harmless, but wasteful).
 179
 180 libgcc_s (GNU)
 181 ^^^^^^^^^^^^^^
 182
 183 `GCC's runtime library <https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html>`_
 184 can be used in place of compiler-rt. However, it lacks several functions
 185 that LLVM may emit references to, particularly when using Clang's
 186 ``__builtin_*_overflow`` family of intrinsics.
 187
 188 You can instruct Clang to use libgcc_s with the ``--rtlib=libgcc`` flag.
 189 This is not supported on every platform.
 190
 191 Atomics library
 192 ---------------
 193
 194 If your program makes use of atomic operations and the compiler is not able
 195 to lower them all directly to machine instructions (because there either is
 196 no known suitable machine instruction or the operand is not known to be
 197 suitably aligned), a call to a runtime library ``__atomic_*`` function
 198 will be generated. A runtime library containing these atomics functions is
 199 necessary for such programs.
 200
 201 compiler-rt (LLVM)
 202 ^^^^^^^^^^^^^^^^^^
 203
 204 compiler-rt contains an implementation of an atomics library.
 205
 206 libatomic (GNU)
 207 ^^^^^^^^^^^^^^^
 208
 209 libgcc_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
 211 used 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
 220 Unwind library
 221 --------------
 222
 223 The unwind library provides a family of ``_Unwind_*`` functions implementing
 224 the 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>`_).
 226 It is a dependency of the C++ ABI library, and sometimes is a dependency
 227 of other runtimes.
 228
 229 libunwind (LLVM)
 230 ^^^^^^^^^^^^^^^^
 231
 232 LLVM's unwinder library is part of the llvm-project git repository. To
 233 build it, pass ``-DLLVM_ENABLE_RUNTIMES=libunwind`` to the cmake invocation.
 234
 235 If using libc++abi, you may need to configure it to use libunwind
 236 rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``
 237 to ``cmake``. If libc++abi is configured to use some version of
 238 libunwind, that library will be implicitly linked into binaries that
 239 link to libc++abi.
 240
 241 libgcc_s (GNU)
 242 ^^^^^^^^^^^^^^
 243
 244 libgcc_s has an integrated unwinder, and does not need an external unwind
 245 library to be provided.
 246
 247 libunwind (nongnu.org)
 248 ^^^^^^^^^^^^^^^^^^^^^^
 249
 250 This is another implementation of the libunwind specification.
 251 See `libunwind (nongnu.org) <https://www.nongnu.org/libunwind>`_.
 252
 253 libunwind (PathScale)
 254 ^^^^^^^^^^^^^^^^^^^^^
 255
 256 This is another implementation of the libunwind specification.
 257 See `libunwind (pathscale) <https://github.com/pathscale/libunwind>`_.
 258
 259 Sanitizer runtime
 260 -----------------
 261
 262 The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly
 263 makes calls to a runtime library, in order to maintain side state about the
 264 execution of the program and to issue diagnostic messages when a problem is
 265 detected.
 266
 267 The only supported implementation of these runtimes is provided by LLVM's
 268 compiler-rt, and the relevant portion of that library
 269 (``libclang_rt.<sanitizer>.<arch>.a``)
 270 will be implicitly linked when linking with a ``-fsanitize=...`` flag.
 271
 272 C standard library
 273 ------------------
 274
 275 Clang supports a wide variety of
 276 `C standard library <https://en.cppreference.com/w/c>`_
 277 implementations.
 278
 279 C++ ABI library
 280 ---------------
 281
 282 The C++ ABI library provides an implementation of the library portion of
 283 the 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>`_.
 288 References to the functions and objects in this library are implicitly
 289 generated by Clang when compiling C++ code.
 290
 291 While it is possible to link C++ code using libstdc++ and code using libc++
 292 together into the same program (so long as you do not attempt to pass C++
 293 standard library objects across the boundary), it is not generally possible
 294 to have more than one C++ ABI library in a program.
 295
 296 The version of the C++ ABI library used by Clang will be the one that the
 297 chosen C++ standard library was linked against. Several implementations are
 298 available:
 299
 300 libc++abi (LLVM)
 301 ^^^^^^^^^^^^^^^^
 302
 303 `libc++abi <https://libcxxabi.llvm.org/>`_ is LLVM's implementation of this
 304 specification.
 305
 306 libsupc++ (GNU)
 307 ^^^^^^^^^^^^^^^
 308
 309 libsupc++ is GCC's implementation of this specification. However, this
 310 library is only used when libstdc++ is linked statically. The dynamic
 311 library 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
 319 libcxxrt (PathScale)
 320 ^^^^^^^^^^^^^^^^^^^^
 321
 322 This is another implementation of the Itanium C++ ABI specification.
 323 See `libcxxrt <https://github.com/pathscale/libcxxrt>`_.
 324
 325 C++ standard library
 326 --------------------
 327
 328 Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation
 329 of the `C++ standard library <https://en.cppreference.com/w/cpp>`_.
 330
 331 libc++ (LLVM)
 332 ^^^^^^^^^^^^^
 333
 334 `libc++ <https://libcxx.llvm.org/>`_ is LLVM's implementation of the C++
 335 standard library, aimed at being a complete implementation of the C++
 336 standards from C++11 onwards.
 337
 338 You can instruct Clang to use libc++ with the ``-stdlib=libc++`` flag.
 339
 340 libstdc++ (GNU)
 341 ^^^^^^^^^^^^^^^
 342
 343 `libstdc++ <https://gcc.gnu.org/onlinedocs/libstdc++/>`_ is GCC's
 344 implementation of the C++ standard library. Clang supports libstdc++
 345 4.8.3 (released 2014-05-22) and later. Historically Clang implemented
 346 workarounds for issues discovered in libstdc++, and these are removed
 347 as fixed libstdc++ becomes sufficiently old.
 348
 349 You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag.