349 lines
12 KiB
ReStructuredText
349 lines
12 KiB
ReStructuredText
===============================
|
|
Assembling a Complete Toolchain
|
|
===============================
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 2
|
|
|
|
Introduction
|
|
============
|
|
|
|
Clang is only one component in a complete tool chain for C family
|
|
programming languages. In order to assemble a complete toolchain,
|
|
additional tools and runtime libraries are required. Clang is designed
|
|
to interoperate with existing tools and libraries for its target
|
|
platforms, and the LLVM project provides alternatives for a number
|
|
of these components.
|
|
|
|
This document describes the required and optional components in a
|
|
complete toolchain, where to find them, and the supported versions
|
|
and limitations of each option.
|
|
|
|
.. warning::
|
|
|
|
This document currently describes Clang configurations on POSIX-like
|
|
operating systems with the GCC-compatible ``clang`` driver. When
|
|
targeting Windows with the MSVC-compatible ``clang-cl`` driver, some
|
|
of the details are different.
|
|
|
|
Tools
|
|
=====
|
|
|
|
.. FIXME: Describe DWARF-related tools
|
|
|
|
A complete compilation of C family programming languages typically
|
|
involves the following pipeline of tools, some of which are omitted
|
|
in some compilations:
|
|
|
|
* **Preprocessor**: This performs the actions of the C preprocessor:
|
|
expanding #includes and #defines.
|
|
The ``-E`` flag instructs Clang to stop after this step.
|
|
|
|
* **Parsing**: This parses and semantically analyzes the source language and
|
|
builds a source-level intermediate representation ("AST"), producing a
|
|
:ref:`precompiled header (PCH) <usersmanual-precompiled-headers>`,
|
|
preamble, or
|
|
:doc:`precompiled module file (PCM) <Modules>`,
|
|
depending on the input.
|
|
The ``-precompile`` flag instructs Clang to stop after this step. This is
|
|
the default when the input is a header file.
|
|
|
|
* **IR generation**: This converts the source-level intermediate representation
|
|
into an optimizer-specific intermediate representation (IR); for Clang, this
|
|
is LLVM IR.
|
|
The ``-emit-llvm`` flag instructs Clang to stop after this step. If combined
|
|
with ``-S``, Clang will produce textual LLVM IR; otherwise, it will produce
|
|
LLVM IR bitcode.
|
|
|
|
* **Compiler backend**: This converts the intermediate representation
|
|
into target-specific assembly code.
|
|
The ``-S`` flag instructs Clang to stop after this step.
|
|
|
|
* **Assembler**: This converts target-specific assembly code into
|
|
target-specific machine code object files.
|
|
The ``-c`` flag instructs Clang to stop after this step.
|
|
|
|
* **Linker**: This combines multiple object files into a single image
|
|
(either a shared object or an executable).
|
|
|
|
Clang provides all of these pieces other than the linker. When multiple
|
|
steps are performed by the same tool, it is common for the steps to be
|
|
fused together to avoid creating intermediate files.
|
|
|
|
When given an output of one of the above steps as an input, earlier steps
|
|
are skipped (for instance, a ``.s`` file input will be assembled and linked).
|
|
|
|
The Clang driver can be invoked with the ``-###`` flag (this argument will need
|
|
to be escaped under most shells) to see which commands it would run for the
|
|
above steps, without running them. The ``-v`` (verbose) flag will print the
|
|
commands in addition to running them.
|
|
|
|
Clang frontend
|
|
--------------
|
|
|
|
The Clang frontend (``clang -cc1``) is used to compile C family languages. The
|
|
command-line interface of the frontend is considered to be an implementation
|
|
detail, intentionally has no external documentation, and is subject to change
|
|
without notice.
|
|
|
|
Language frontends for other languages
|
|
--------------------------------------
|
|
|
|
Clang can be provided with inputs written in non-C-family languages. In such
|
|
cases, an external tool will be used to compile the input. The
|
|
currently-supported languages are:
|
|
|
|
* Ada (``-x ada``, ``.ad[bs]``)
|
|
* Fortran (``-x f95``, ``.f``, ``.f9[05]``, ``.for``, ``.fpp``, case-insensitive)
|
|
* Java (``-x java``)
|
|
|
|
In each case, GCC will be invoked to compile the input.
|
|
|
|
Assembler
|
|
---------
|
|
|
|
Clang can either use LLVM's integrated assembler or an external system-specific
|
|
tool (for instance, the GNU Assembler on GNU OSes) to produce machine code from
|
|
assembly.
|
|
By default, Clang uses LLVM's integrated assembler on all targets where it is
|
|
supported. If you wish to use the system assembler instead, use the
|
|
``-fno-integrated-as`` option.
|
|
|
|
Linker
|
|
------
|
|
|
|
Clang can be configured to use one of several different linkers:
|
|
|
|
* GNU ld
|
|
* GNU gold
|
|
* LLVM's `lld <https://lld.llvm.org>`_
|
|
* MSVC's link.exe
|
|
|
|
Link-time optimization is natively supported by lld, and supported via
|
|
a `linker plugin <https://llvm.org/docs/GoldPlugin.html>`_ when using gold.
|
|
|
|
The default linker varies between targets, and can be overridden via the
|
|
``-fuse-ld=<linker name>`` flag.
|
|
|
|
Runtime libraries
|
|
=================
|
|
|
|
A number of different runtime libraries are required to provide different
|
|
layers of support for C family programs. Clang will implicitly link an
|
|
appropriate implementation of each runtime library, selected based on
|
|
target defaults or explicitly selected by the ``--rtlib=`` and ``--stdlib=``
|
|
flags.
|
|
|
|
The set of implicitly-linked libraries depend on the language mode. As a
|
|
consequence, you should use ``clang++`` when linking C++ programs in order
|
|
to ensure the C++ runtimes are provided.
|
|
|
|
.. note::
|
|
|
|
There may exist other implementations for these components not described
|
|
below. Please let us know how well those other implementations work with
|
|
Clang so they can be added to this list!
|
|
|
|
.. FIXME: Describe Objective-C runtime libraries
|
|
.. FIXME: Describe profiling runtime library
|
|
.. FIXME: Describe cuda/openmp/opencl/... runtime libraries
|
|
|
|
Compiler runtime
|
|
----------------
|
|
|
|
The compiler runtime library provides definitions of functions implicitly
|
|
invoked by the compiler to support operations not natively supported by
|
|
the underlying hardware (for instance, 128-bit integer multiplications),
|
|
and where inline expansion of the operation is deemed unsuitable.
|
|
|
|
The default runtime library is target-specific. For targets where GCC is
|
|
the dominant compiler, Clang currently defaults to using libgcc_s. On most
|
|
other targets, compiler-rt is used by default.
|
|
|
|
compiler-rt (LLVM)
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
`LLVM's compiler runtime library <https://compiler-rt.llvm.org/>`_ provides a
|
|
complete set of runtime library functions containing all functions that
|
|
Clang will implicitly call, in ``libclang_rt.builtins.<arch>.a``.
|
|
|
|
You can instruct Clang to use compiler-rt with the ``--rtlib=compiler-rt`` flag.
|
|
This is not supported on every platform.
|
|
|
|
If using libc++ and/or libc++abi, you may need to configure them to use
|
|
compiler-rt rather than libgcc_s by passing ``-DLIBCXX_USE_COMPILER_RT=YES``
|
|
and/or ``-DLIBCXXABI_USE_COMPILER_RT=YES`` to ``cmake``. Otherwise, you
|
|
may end up with both runtime libraries linked into your program (this is
|
|
typically harmless, but wasteful).
|
|
|
|
libgcc_s (GNU)
|
|
^^^^^^^^^^^^^^
|
|
|
|
`GCC's runtime library <https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html>`_
|
|
can be used in place of compiler-rt. However, it lacks several functions
|
|
that LLVM may emit references to, particularly when using Clang's
|
|
``__builtin_*_overflow`` family of intrinsics.
|
|
|
|
You can instruct Clang to use libgcc_s with the ``--rtlib=libgcc`` flag.
|
|
This is not supported on every platform.
|
|
|
|
Atomics library
|
|
---------------
|
|
|
|
If your program makes use of atomic operations and the compiler is not able
|
|
to lower them all directly to machine instructions (because there either is
|
|
no known suitable machine instruction or the operand is not known to be
|
|
suitably aligned), a call to a runtime library ``__atomic_*`` function
|
|
will be generated. A runtime library containing these atomics functions is
|
|
necessary for such programs.
|
|
|
|
compiler-rt (LLVM)
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
compiler-rt contains an implementation of an atomics library.
|
|
|
|
libatomic (GNU)
|
|
^^^^^^^^^^^^^^^
|
|
|
|
libgcc_s does not provide an implementation of an atomics library. Instead,
|
|
`GCC's libatomic library <https://gcc.gnu.org/wiki/Atomic/GCCMM>`_ can be
|
|
used to supply these when using libgcc_s.
|
|
|
|
.. note::
|
|
|
|
Clang does not currently automatically link against libatomic when using
|
|
libgcc_s. You may need to manually add ``-latomic`` to support this
|
|
configuration when using non-native atomic operations (if you see link errors
|
|
referring to ``__atomic_*`` functions).
|
|
|
|
Unwind library
|
|
--------------
|
|
|
|
The unwind library provides a family of ``_Unwind_*`` functions implementing
|
|
the language-neutral stack unwinding portion of the Itanium C++ ABI
|
|
(`Level I <https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#base-abi>`_).
|
|
It is a dependency of the C++ ABI library, and sometimes is a dependency
|
|
of other runtimes.
|
|
|
|
libunwind (LLVM)
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
LLVM's unwinder library is part of the llvm-project git repository. To
|
|
build it, pass ``-DLLVM_ENABLE_PROJECTS=libunwind`` to the cmake invocation.
|
|
|
|
If using libc++abi, you may need to configure it to use libunwind
|
|
rather than libgcc_s by passing ``-DLIBCXXABI_USE_LLVM_UNWINDER=YES``
|
|
to ``cmake``. If libc++abi is configured to use some version of
|
|
libunwind, that library will be implicitly linked into binaries that
|
|
link to libc++abi.
|
|
|
|
libgcc_s (GNU)
|
|
^^^^^^^^^^^^^^
|
|
|
|
libgcc_s has an integrated unwinder, and does not need an external unwind
|
|
library to be provided.
|
|
|
|
libunwind (nongnu.org)
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This is another implementation of the libunwind specification.
|
|
See `libunwind (nongnu.org) <https://www.nongnu.org/libunwind>`_.
|
|
|
|
libunwind (PathScale)
|
|
^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This is another implementation of the libunwind specification.
|
|
See `libunwind (pathscale) <https://github.com/pathscale/libunwind>`_.
|
|
|
|
Sanitizer runtime
|
|
-----------------
|
|
|
|
The instrumentation added by Clang's sanitizers (``-fsanitize=...``) implicitly
|
|
makes calls to a runtime library, in order to maintain side state about the
|
|
execution of the program and to issue diagnostic messages when a problem is
|
|
detected.
|
|
|
|
The only supported implementation of these runtimes is provided by LLVM's
|
|
compiler-rt, and the relevant portion of that library
|
|
(``libclang_rt.<sanitizer>.<arch>.a``)
|
|
will be implicitly linked when linking with a ``-fsanitize=...`` flag.
|
|
|
|
C standard library
|
|
------------------
|
|
|
|
Clang supports a wide variety of
|
|
`C standard library <https://en.cppreference.com/w/c>`_
|
|
implementations.
|
|
|
|
C++ ABI library
|
|
---------------
|
|
|
|
The C++ ABI library provides an implementation of the library portion of
|
|
the Itanium C++ ABI, covering both the
|
|
`support functionality in the main Itanium C++ ABI document
|
|
<https://itanium-cxx-abi.github.io/cxx-abi/abi.html>`_ and
|
|
`Level II of the exception handling support
|
|
<https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html#cxx-abi>`_.
|
|
References to the functions and objects in this library are implicitly
|
|
generated by Clang when compiling C++ code.
|
|
|
|
While it is possible to link C++ code using libstdc++ and code using libc++
|
|
together into the same program (so long as you do not attempt to pass C++
|
|
standard library objects across the boundary), it is not generally possible
|
|
to have more than one C++ ABI library in a program.
|
|
|
|
The version of the C++ ABI library used by Clang will be the one that the
|
|
chosen C++ standard library was linked against. Several implementations are
|
|
available:
|
|
|
|
libc++abi (LLVM)
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
`libc++abi <https://libcxxabi.llvm.org/>`_ is LLVM's implementation of this
|
|
specification.
|
|
|
|
libsupc++ (GNU)
|
|
^^^^^^^^^^^^^^^
|
|
|
|
libsupc++ is GCC's implementation of this specification. However, this
|
|
library is only used when libstdc++ is linked statically. The dynamic
|
|
library version of libstdc++ contains a copy of libsupc++.
|
|
|
|
.. note::
|
|
|
|
Clang does not currently automatically link against libatomic when statically
|
|
linking libstdc++. You may need to manually add ``-lsupc++`` to support this
|
|
configuration when using ``-static`` or ``-static-libstdc++``.
|
|
|
|
libcxxrt (PathScale)
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
This is another implementation of the Itanium C++ ABI specification.
|
|
See `libcxxrt <https://github.com/pathscale/libcxxrt>`_.
|
|
|
|
C++ standard library
|
|
--------------------
|
|
|
|
Clang supports use of either LLVM's libc++ or GCC's libstdc++ implementation
|
|
of the `C++ standard library <https://en.cppreference.com/w/cpp>`_.
|
|
|
|
libc++ (LLVM)
|
|
^^^^^^^^^^^^^
|
|
|
|
`libc++ <https://libcxx.llvm.org/>`_ is LLVM's implementation of the C++
|
|
standard library, aimed at being a complete implementation of the C++
|
|
standards from C++11 onwards.
|
|
|
|
You can instruct Clang to use libc++ with the ``-stdlib=libc++`` flag.
|
|
|
|
libstdc++ (GNU)
|
|
^^^^^^^^^^^^^^^
|
|
|
|
`libstdc++ <https://gcc.gnu.org/onlinedocs/libstdc++/>`_ is GCC's implementation
|
|
of the C++ standard library. Clang supports a wide range of versions of
|
|
libstdc++, from around version 4.2 onwards, and will implicitly work around
|
|
some bugs in older versions of libstdc++.
|
|
|
|
You can instruct Clang to use libstdc++ with the ``-stdlib=libstdc++`` flag.
|