granicus.if.org Git - clang/blob - 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 Assember
 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 integrataed assembler on all targets where it is
 110 supported. If you wish to use the system assember 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 <http://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 <http://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 <http://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 <http://mentorembedded.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 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
 238 When checked out into projects/libunwind within an LLVM checkout,
 239 it should be automatically picked up by the LLVM build system.
 240
 241 If using libc++abi, you may need to configure it to use libunwind
 242 rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``
 243 to ``cmake``. If libc++abi is configured to use some version of
 244 libunwind, that library will be implicitly linked into binaries that
 245 link to libc++abi.
 246
 247 libgcc_s (GNU)
 248 ^^^^^^^^^^^^^^
 249
 250 libgcc_s has an integrated unwinder, and does not need an external unwind
 251 library to be provided.
 252
 253 libunwind (nongnu.org)
 254 ^^^^^^^^^^^^^^^^^^^^^^
 255
 256 This is another implementation of the libunwind specification.
 257 See `libunwind (nongnu.org) <http://www.nongnu.org/libunwind>`_.
 258
 259 libunwind (PathScale)
 260 ^^^^^^^^^^^^^^^^^^^^^
 261
 262 This is another implementation of the libunwind specification.
 263 See `libunwind (pathscale) <https://github.com/pathscale/libunwind>`_.
 264
 265 Sanitizer runtime
 266 -----------------
 267
 268 The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly
 269 makes calls to a runtime library, in order to maintain side state about the
 270 execution of the program and to issue diagnostic messages when a problem is
 271 detected.
 272
 273 The only supported implementation of these runtimes is provided by LLVM's
 274 compiler-rt, and the relevant portion of that library
 275 (``libclang_rt.<sanitizer>.<arch>.a``)
 276 will be implicitly linked when linking with a ``-fsanitize=...`` flag.
 277
 278 C standard library
 279 ------------------
 280
 281 Clang supports a wide variety of
 282 `C standard library <http://en.cppreference.com/w/c>`_
 283 implementations.
 284
 285 C++ ABI library
 286 ---------------
 287
 288 The C++ ABI library provides an implementation of the library portion of
 289 the Itanium C++ ABI, covering both the
 290 `support functionality in the main Itanium C++ ABI document
 291 <http://mentorembedded.github.io/cxx-abi/abi.html>`_ and
 292 `Level II of the exception handling support
 293 <http://mentorembedded.github.io/cxx-abi/abi-eh.html#cxx-abi>`_.
 294 References to the functions and objects in this library are implicitly
 295 generated by Clang when compiling C++ code.
 296
 297 While it is possible to link C++ code using libstdc++ and code using libc++
 298 together into the same program (so long as you do not attempt to pass C++
 299 standard library objects across the boundary), it is not generally possible
 300 to have more than one C++ ABI library in a program.
 301
 302 The version of the C++ ABI library used by Clang will be the one that the
 303 chosen C++ standard library was linked against. Several implementations are
 304 available:
 305
 306 libc++abi (LLVM)
 307 ^^^^^^^^^^^^^^^^
 308
 309 `libc++abi <http://libcxxabi.llvm.org/>`_ is LLVM's implementation of this
 310 specification.
 311
 312 libsupc++ (GNU)
 313 ^^^^^^^^^^^^^^^
 314
 315 libsupc++ is GCC's implementation of this specification. However, this
 316 library is only used when libstdc++ is linked statically. The dynamic
 317 library 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
 325 libcxxrt (PathScale)
 326 ^^^^^^^^^^^^^^^^^^^^
 327
 328 This is another implementation of the Itanium C++ ABI specification.
 329 See `libcxxrt <https://github.com/pathscale/libcxxrt>`_.
 330
 331 C++ standard library
 332 --------------------
 333
 334 Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation
 335 of the `C++ standard library <http://en.cppreference.com/w/cpp>`_.
 336
 337 libc++ (LLVM)
 338 ^^^^^^^^^^^^^
 339
 340 `libc++ <http://libcxx.llvm.org/>`_ is LLVM's implementation of the C++
 341 standard library, aimed at being a complete implementation of the C++
 342 standards from C++11 onwards.
 343
 344 You can instruct Clang to use libc++ with the ``-stdlib=libc++`` flag.
 345
 346 libstdc++ (GNU)
 347 ^^^^^^^^^^^^^^^
 348
 349 `libstdc++ <https://gcc.gnu.org/onlinedocs/libstdc++/>`_ is GCC's implementation
 350 of the C++ standard library. Clang supports a wide range of versions of
 351 libstdc++, from around version 4.2 onwards, and will implicitly work around
 352 some bugs in older versions of libstdc++.
 353
 354 You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag.