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