| 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_PROJECTS=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 libatomic 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 implementation |
|---|
| 344 | of the C++ standard library. Clang supports a wide range of versions of |
|---|
| 345 | libstdc++, from around version 4.2 onwards, and will implicitly work around |
|---|
| 346 | some bugs in older versions of libstdc++. |
|---|
| 347 | |
|---|
| 348 | You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag. |
|---|
| 349 | |
|---|