(Agreed, thanks!)
~Will
On Sat, Oct 29, 2016 at 5:50 PM, Sean Silva via cfe-commits
wrote:
> This is awesome Richard. Thanks!
>
> -- Sean Silva
>
> On Thu, Oct 27, 2016 at 1:55 PM, Richard Smith via cfe-commits
> 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) `,
>> + preamble, or
>> + :doc:`precompiled module file (PCM) `,
>> + 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 inpu
