Add documentation describing the components of a complete toolchain including Clang.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@285341 91177308-0d34-0410-b5e6-96231b3b80d8

Author: zygoloid

docs/Toolchain.rst

@@ -0,0 +1,354 @@
+===============================
+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.
+
+Assember
+--------
+
+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 integrataed assembler on all targets where it is
+supported. If you wish to use the system assember 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 <http://lld.llvm.org>`_
+* MSVC's link.exe
+
+Link-time optimization is natively supported by lld, and supported via
+a `linker plugin <http://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 <http://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 <http://mentorembedded.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 can be obtained from subversion:
+
+.. code-block:: console
+
+  llvm-src$ svn co http://llvm.org/svn/llvm-project/libunwind/trunk projects/libunwind
+
+When checked out into projects/libunwind within an LLVM checkout,
+it should be automatically picked up by the LLVM build system.
+
+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) <http://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 <http://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
+<http://mentorembedded.github.io/cxx-abi/abi.html>`_ and
+`Level II of the exception handling support
+<http://mentorembedded.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 <http://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 <http://en.cppreference.com/w/cpp>`_.
+
+libc++ (LLVM)
+^^^^^^^^^^^^^
+
+`libc++ <http://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.

docs/UsersManual.rst

@@ -25,6 +25,10 @@ processes code, please see :doc:`InternalsManual`. If you are interested in the
 `Clang Static Analyzer <http://clang-analyzer.llvm.org>`_, please see its web
 page.
 
+Clang is one component in a complete toolchain for C family languages.
+A separate document describes the other pieces necessary to
+:doc:`assemble a complete toolchain <Toolchain>`.
+
 Clang is designed to support the C family of programming languages,
 which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
 :ref:`Objective-C++ <objcxx>` as well as many dialects of those. For

docs/index.rst

@@ -17,6 +17,7 @@ Using Clang as a Compiler
    :maxdepth: 1
 
    UsersManual
+   Toolchain
    LanguageExtensions
    AttributeReference
    DiagnosticsReference