<div dir="ltr"><div>Nice!</div><div><br></div><div>For consistency with other docs, can you rename this to AdvancedBuilds or AdvancedBuildConfigurations?</div><div><br></div>A couple comments about non-ascii characters inline:<div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Mar 18, 2016 at 2:16 PM, Chris Bieneman via llvm-commits <span dir="ltr"><<a href="mailto:llvm-commits@lists.llvm.org" target="_blank">llvm-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: cbieneman<br>
Date: Fri Mar 18 16:16:26 2016<br>
New Revision: 263834<br>
<br>
URL: <a href="http://llvm.org/viewvc/llvm-project?rev=263834&view=rev" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project?rev=263834&view=rev</a><br>
Log:<br>
[Docs] New documentation for advanced build configurations<br>
<br>
This document covers how to use some of the new complex build configurations CMake supports.<br>
<br>
Feedback and improvements welcomed!<br>
<br>
Added:<br>
    llvm/trunk/docs/Advanced_Builds.rst<br>
Modified:<br>
    llvm/trunk/docs/CMake.rst<br>
    llvm/trunk/docs/index.rst<br>
<br>
Added: llvm/trunk/docs/Advanced_Builds.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/Advanced_Builds.rst?rev=263834&view=auto" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/Advanced_Builds.rst?rev=263834&view=auto</a><br>
==============================================================================<br>
--- llvm/trunk/docs/Advanced_Builds.rst (added)<br>
+++ llvm/trunk/docs/Advanced_Builds.rst Fri Mar 18 16:16:26 2016<br>
@@ -0,0 +1,174 @@<br>
+=============================<br>
+Advanced Build Configurations<br>
+=============================<br>
+<br>
+.. contents::<br>
+   :local:<br>
+<br>
+Introduction<br>
+============<br>
+<br>
+`CMake <<a href="http://www.cmake.org/" rel="noreferrer" target="_blank">http://www.cmake.org/</a>>`_ is a cross-platform build-generator tool. CMake<br>
+does not build the project, it generates the files needed by your build tool<br>
+(GNU make, Visual Studio, etc.) for building LLVM.<br>
+<br>
+If **you are a new contributor**, please start with the :doc:`GettingStarted` or<br>
+:doc:`CMake` pages. This page is intended for users doing more complex builds.<br>
+<br>
+Many of the examples below are written assuming specific CMake Generators.<br>
+Unless otherwise explicitly called out these commands should work with any CMake<br>
+generator.<br>
+<br>
+Bootstrap Builds<br>
+================<br>
+<br>
+The Clang CMake build system supports bootstrap (aka multi-stage) builds. At a<br>
+high level a multi-stage build is a chain of builds that pass data from one<br>
+stage into the next. The most common and simple version of this is a traditional<br>
+bootstrap build.<br>
+<br>
+In a simple two-stage bootstrap build, we build clang using the system compiler,<br>
+then use that just-built clang to build clang again. In CMake this simplest form<br>
+of a bootstrap build can be configured with a single option,<br>
+CLANG_ENABLE_BOOTSTRAP.<br>
+<br>
+.. code-block:: console<br>
+<br>
+  $ make -G Ninja -DCLANG_ENABLE_BOOTSTRAP=On <path to source><br>
+  $ ninja stage2<br>
+<br>
+This command itself isn’t terribly useful because it assumes default<br></blockquote><div><br></div><div>Non-ascii</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+configurations for each stage. The next series of examples utilize CMake cache<br>
+scripts to provide more complex options.<br>
+<br>
+The clang build system refers to builds as stages. A stage1 build is a standard<br>
+build using the compiler installed on the host, and a stage2 build is built<br>
+using the stage1 compiler. This nomenclature holds up to more stages too. In<br>
+general a stage*n* build is built using the output from stage*n-1*.<br>
+<br>
+Apple Clang Builds (A More Complex Bootstrap)<br>
+=============================================<br>
+<br>
+Apple’s Clang builds are a slightly more complicated example of the simple<br></blockquote><div><br></div><div>Non-ascii</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+bootstrapping scenario. Apple Clang is built using a 2-stage build.<br>
+<br>
+The stage1 compiler is a host-only compiler with some options set. The stage1<br>
+compiler is a balance of optimization vs build time because it is a throwaway.<br>
+The stage2 compiler is the fully optimized compiler intended to ship to users.<br>
+<br>
+Setting up these compilers requires a lot of options. To simplify the<br>
+configuration the Apple Clang build settings are contained in CMake Cache files.<br>
+You can build an Apple Clang compiler using the following commands:<br>
+<br>
+.. code-block:: console<br>
+<br>
+  $ make -G Ninja -C <path to clang>/cmake/caches/Apple-stage1.cmake <path to source><br>
+  $ ninja stage2-distribution<br>
+<br>
+This CMake invocation configures the stage1 host compiler, and sets<br>
+CLANG_BOOTSTRAP_CMAKE_ARGS to pass the Apple-stage2.cmake cache script to the<br>
+stage2 configuration step.<br>
+<br>
+When you build the stage2-distribution target it builds the minimal stage1<br>
+compiler and required tools, then configures and builds the stage2 compiler<br>
+based on the settings in Apple-stage2.cmake.<br>
+<br>
+This pattern of using cache scripts to set complex settings, and specifically to<br>
+make later stage builds include cache scripts is common in our more advanced<br>
+build configurations.<br>
+<br>
+Multi-stage PGO<br>
+===============<br>
+<br>
+Profile-Guided Optimizations (PGO) is a really great way to optimize the code<br>
+clang generates. Our multi-stage PGO builds are a workflow for generating PGO<br>
+profiles that can be used to optimize clang.<br>
+<br>
+At a high level, the way PGO works is that you build an instrumented compiler,<br>
+then you run the instrumented compiler against sample source files. While the<br>
+instrumented compiler runs it will output a bunch of files containing<br>
+performance counters (.profraw files). After generating all the profraw files<br>
+you use llvm-profdata to merge the files into a single profdata file that you<br>
+can feed into the LLVM_PROFDATA_FILE option.<br>
+<br>
+Our PGO.cmake cache script automates that whole process. You can use it by<br>
+running:<br>
+<br>
+.. code-block:: console<br>
+<br>
+  $ make -G Ninja -C <path_to_clang>/cmake/caches/PGO.cmake <source dir><br>
+  $ ninja stage2-instrumented-generate-profdata<br>
+<br>
+If you let that run for a few hours or so, it will place a profdata file in your<br>
+build directory. This takes a really long time because it builds clang twice,<br>
+and you *must* have compiler-rt in your build tree.<br>
+<br>
+This process uses any source files under the perf-training directory as training<br>
+data as long as the source files are marked up with LIT-style RUN lines.<br>
+<br>
+After it finishes you can use â€œfind . -name clang.profdata† to find it, but it<br>
+should be at a path something like:<br>
+<br>
+.. code-block:: console<br>
+<br>
+  <build dir>/tools/clang/stage2-instrumented-bins/utils/perf-training/clang.profdata<br>
+<br>
+You can feed that file into the LLVM_PROFDATA_FILE option when you build your<br>
+optimized compiler.<br>
+<br>
+The PGO came cache has a slightly different stage naming scheme than other<br>
+multi-stage builds. It generates three stages; stage1, stage2-instrumented, and<br>
+stage2. Both of the stage2 builds are built using the stage1 compiler.<br>
+<br>
+The PGO came cache generates the following additional targets:<br>
+<br>
+**stage2-instrumented**<br>
+  Builds a stage1 x86 compiler, runtime, and required tools (llvm-config,<br>
+  llvm-profdata) then uses that compiler to build an instrumented stage2 compiler.<br>
+<br>
+**stage2-instrumented-generate-profdata**<br>
+  Depends on â€œstage2-instrumented† and will use the instrumented compiler to<br>
+  generate profdata based on the training files in <clang>/utils/perf-training<br>
+<br>
+**stage2**<br>
+  Depends of â€œstage2-instrumented-generate-profdata† and will use the stage1<br></blockquote><div><br></div><div>Non-ascii</div><div><br></div><div>-- Sean Silva</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+  compiler with the stage2 profdata to build a PGO-optimized compiler.<br>
+<br>
+**stage2-check-llvm**<br>
+  Depends on stage2 and runs check-llvm using the stage2 compiler.<br>
+<br>
+**stage2-check-clang**<br>
+  Depends on stage2 and runs check-clang using the stage2 compiler.<br>
+<br>
+**stage2-check-all**<br>
+  Depends on stage2 and runs check-all using the stage2 compiler.<br>
+<br>
+**stage2-test-suite**<br>
+  Depends on stage2 and runs the test-suite using the stage3 compiler (requires<br>
+  in-tree test-suite).<br>
+<br>
+3-Stage Non-Determinism<br>
+=======================<br>
+<br>
+In the ancient lore of compilers non-determinism is like the multi-headed hydra.<br>
+Whenever it's head pops up, terror and chaos ensue.<br>
+<br>
+Historically one of the tests to verify that a compiler was deterministic would<br>
+be a three stage build. The idea of a three stage build is you take your sources<br>
+and build a compiler (stage1), then use that compiler to rebuild the sources<br>
+(stage2), then you use that compiler to rebuild the sources a third time<br>
+(stage3) with an identical configuration to the stage2 build. At the end of<br>
+this, you have a stage2 and stage3 compiler that should be bit-for-bit<br>
+identical.<br>
+<br>
+You can perform one of these 3-stage builds with LLVM & clang using the<br>
+following commands:<br>
+<br>
+.. code-block:: console<br>
+<br>
+  $ cmake -G Ninja -C <path_to_clang>/cmake/caches/3-stage.cmake <source dir><br>
+  $ ninja stage3<br>
+<br>
+After the build you can compare the stage2 & stage3 compilers. We have a bot<br>
+setup `here <<a href="http://lab.llvm.org:8011/builders/clang-3stage-ubuntu" rel="noreferrer" target="_blank">http://lab.llvm.org:8011/builders/clang-3stage-ubuntu</a>>`_ that runs<br>
+this build and compare configuration.<br>
<br>
Modified: llvm/trunk/docs/CMake.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CMake.rst?rev=263834&r1=263833&r2=263834&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CMake.rst?rev=263834&r1=263833&r2=263834&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/CMake.rst (original)<br>
+++ llvm/trunk/docs/CMake.rst Fri Mar 18 16:16:26 2016<br>
@@ -474,6 +474,41 @@ LLVM-specific variables<br>
             If you want to build LLVM as a shared library, you should use the<br>
             ``LLVM_BUILD_LLVM_DYLIB`` option.<br>
<br>
+CMake Caches<br>
+============<br>
+<br>
+Recently LLVM and Clang have been adding some more complicated build system<br>
+features. Utilizing these new features often involves a complicated chain of<br>
+CMake variables passed on the command line. Clang provides a collection of CMake<br>
+cache scripts to make these features more approachable.<br>
+<br>
+CMake cache files are utilized using CMake's -C flag:<br>
+<br>
+.. code-block:: console<br>
+<br>
+  $ cmake -C <path to cache file> <path to sources><br>
+<br>
+CMake cache scripts are processed in an isolated scope, only cached variables<br>
+remain set when the main configuration runs. CMake cached variables do not reset<br>
+variables that are already set unless the FORCE option is specified.<br>
+<br>
+A few notes about CMake Caches:<br>
+<br>
+- Order of command line arguments is important<br>
+<br>
+  - -D arguments specified before -C are set before the cache is processed and<br>
+    can be read inside the cache file<br>
+  - -D arguments specified after -C are set after the cache is processed and<br>
+    are unset inside the cache file<br>
+<br>
+- All -D arguments will override cache file settings<br>
+- CMAKE_TOOLCHAIN_FILE is evaluated after both the cache file and the command<br>
+  line arguments<br>
+- It is recommended that all -D options should be specified *before* -C<br>
+<br>
+For more information about some of the advanced build configurations supported<br>
+via Cache files see :doc:`Advanced_Builds`.<br>
+<br>
 Executing the test suite<br>
 ========================<br>
<br>
<br>
Modified: llvm/trunk/docs/index.rst<br>
URL: <a href="http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=263834&r1=263833&r2=263834&view=diff" rel="noreferrer" target="_blank">http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/index.rst?rev=263834&r1=263833&r2=263834&view=diff</a><br>
==============================================================================<br>
--- llvm/trunk/docs/index.rst (original)<br>
+++ llvm/trunk/docs/index.rst Fri Mar 18 16:16:26 2016<br>
@@ -65,6 +65,7 @@ representation.<br>
    :hidden:<br>
<br>
    CMake<br>
+   Advanced_Builds<br>
    HowToBuildOnARM<br>
    HowToCrossCompileLLVM<br>
    CommandGuide/index<br>
<br>
<br>
_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@lists.llvm.org">llvm-commits@lists.llvm.org</a><br>
<a href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits" rel="noreferrer" target="_blank">http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits</a><br>
</blockquote></div><br></div></div></div>