This is awesome Richard. Thanks! -- Sean Silva
On Thu, Oct 27, 2016 at 1:55 PM, Richard Smith via cfe-commits < cfe-commits@lists.llvm.org> wrote: > Author: rsmith > Date: Thu Oct 27 15:55:56 2016 > New Revision: 285341 > > URL: http://llvm.org/viewvc/llvm-project?rev=285341&view=rev > Log: > Add documentation describing the components of a complete toolchain > including Clang. > > Added: > cfe/trunk/docs/Toolchain.rst > Modified: > cfe/trunk/docs/UsersManual.rst > cfe/trunk/docs/index.rst > > Added: cfe/trunk/docs/Toolchain.rst > URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ > Toolchain.rst?rev=285341&view=auto > ============================================================ > ================== > --- cfe/trunk/docs/Toolchain.rst (added) > +++ cfe/trunk/docs/Toolchain.rst Thu Oct 27 15:55:56 2016 > @@ -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. > > Modified: cfe/trunk/docs/UsersManual.rst > URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ > UsersManual.rst?rev=285341&r1=285340&r2=285341&view=diff > ============================================================ > ================== > --- cfe/trunk/docs/UsersManual.rst (original) > +++ cfe/trunk/docs/UsersManual.rst Thu Oct 27 15:55:56 2016 > @@ -25,6 +25,10 @@ processes code, please see :doc:`Interna > `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 > > Modified: cfe/trunk/docs/index.rst > URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index. > rst?rev=285341&r1=285340&r2=285341&view=diff > ============================================================ > ================== > --- cfe/trunk/docs/index.rst (original) > +++ cfe/trunk/docs/index.rst Thu Oct 27 15:55:56 2016 > @@ -17,6 +17,7 @@ Using Clang as a Compiler > :maxdepth: 1 > > UsersManual > + Toolchain > LanguageExtensions > AttributeReference > DiagnosticsReference > > > _______________________________________________ > cfe-commits mailing list > cfe-commits@lists.llvm.org > http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits >
_______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits