[docs] Add new document on building distributions

[beanz]

Summary

This document is an attempt to provide a guide for best practices for using the LLVM build system to generate distributable LLVM-based tools.

Most of the document is geared toward distributions of LLVM-based toolchains, but much of it also applies to distributing other LLVM-based tools and libraries.

[tstellar]

This is very useful, thanks for writing this up.

[dschuff]

This is great! Might it be worth mentioning LLVM_INSTALL_TOOLCHAIN_ONLY somewhere?

[beanz]

In D62040#1505692, @dschuff wrote:

This is great! Might it be worth mentioning LLVM_INSTALL_TOOLCHAIN_ONLY somewhere?

I kinda have mixed feelings about that. I want to discourage people from using the install target when building distributions because I think that if you are building a distribution you should be conscious of exactly what goes into it. The install-distribution target does that in a much cleaner interface than the install target provides. That said, it is probably worth a mention, and I should explain the differences in expected behavior between install and `install-distribution.

[beanz]

Adding information about distribution targets and LLVM_INSTALL_TOOLCHAIN_ONLY.

[winksaville]

A few suggestions to consider, but this is GREAT, thanks!

llvm/docs/BuildingADistribution.rst

54

"Due to design and implemenation decisions in LLVM relies on" can be improved, maybe remove "in" and add a comma; "Due to design and implemenation decisions, LLVM relies on ..."

87

Is distributation target an internal target that shouldn't be used or a convenience target and might be used by the people building the distribution ? If the former consider saying "internal build target".

109

Consider adding' with "BOOTSTRAP_*, see :doc:AdvancedBuilds.

113

I suggest simplifying 110..112 to something like:

"The first and simplest way to control the optimization is using CMAKE_BUILD_TYPE. The main ..."

124

Consider changing "includes static archives" to "includes static libraries" as archives isn't used anywhere else.

156

Maybe add "see :doc:CMake"

189

Consider moving to ":doc:CMake" and then added to the "already documented" list above?

[beanz]

llvm/docs/BuildingADistribution.rst

87

If you want to install a distribution onto your local system into a path that requires sudo, and you don’t want to build everything, you need to use it. It is also a handy from a workflow perspective. If it were only for internal build system purposes I would likely not have made it a target.

124

I’m not sure what you mean by the term “archive” not being used elsewhere. We use the term “static archive” and “static library” pretty interchangeably around LLVM. It is really a matter of preference and often whether you come from a Unix background where archives are created with an archiver (ar).

189

This is an uncommon setting to alter, and we really don’t want that document to have an exhaustive list of our options.

[beanz]

Updates based on @winksaville's feedback

[hans]

Interesting! I didn't know about most of this.

I want to discourage people from using the install target when building distributions because I think that if you are building a distribution you should be conscious of exactly what goes into it. The install-distribution target does that in a much cleaner interface than the install target provides.

But the install target is kind of a standard cmake thing; wouldn't it be better if we made that target good? That's also what the cmake "package" target uses, which is what we use to build the Windows installer.

llvm/docs/BuildingADistribution.rst

203

I thought it defaults to OFF?

llvm/CMakeLists.txt:221:option(LLVM_INSTALL_TOOLCHAIN_ONLY "Only include toolchain files in the 'install' target." OFF)

[beanz]

In D62040#1506176, @hans wrote:

But the install target is kind of a standard cmake thing; wouldn't it be better if we made that target good? That's also what the cmake "package" target uses, which is what we use to build the Windows installer.

It has been a while since I introduced this stuff (3 years now), but the rationale was that the install target and the all target aren't really well exposed in CMake. One of the goals of this was to reduce build time for generating distributions, and there is no way in CMake to "build only the things that get installed" without running the `install` target.

I should look at how the package target works. I suspect there may be a way to make a package-distribution target.

[beanz]

llvm/docs/BuildingADistribution.rst

203

You're right. Good catch.

[beanz]

Fixing the wording around LLVM_INSTALL_TOOLCHAIN_ONLY

[beanz]

@hans I have some ideas on how to make package work. There is a simple solution to make it work as long as you're not using any runtime components, but I have an idea on how to make it work with runtime components.

[hans]

In D62040#1506813, @beanz wrote:

@hans I have some ideas on how to make package work. There is a simple solution to make it work as long as you're not using any runtime components, but I have an idea on how to make it work with runtime components.

The Windows packages currently includes at least the asan runtime (and a bunch of other stuff like openmp that people ask for but I'm never quite sure if it works).

[beanz]

In D62040#1506826, @hans wrote:

The Windows packages currently includes at least the asan runtime (and a bunch of other stuff like openmp that people ask for but I'm never quite sure if it works).

But I assume you're not building them using the just-built clang (LLVM_ENABLE_RUNTIMES). I'm not sure how any of our current mechanisms for installing those would work with cpack.

[hans]

In D62040#1506830, @beanz wrote:

In D62040#1506826, @hans wrote:

The Windows packages currently includes at least the asan runtime (and a bunch of other stuff like openmp that people ask for but I'm never quite sure if it works).

But I assume you're not building them using the just-built clang (LLVM_ENABLE_RUNTIMES). I'm not sure how any of our current mechanisms for installing those would work with cpack.

Hmm, I've never set LLVM_ENABLE_RUNTIMES, I just build with a previously built clang. The script lives in utils/release/build_llvm_package.bat

[beanz]

In D62040#1506832, @hans wrote:

Hmm, I've never set LLVM_ENABLE_RUNTIMES, I just build with a previously built clang. The script lives in utils/release/build_llvm_package.bat

Given that there is a one-line fix to make the package target install the distribution list of components. I'm working on making this work for the runtimes build too.

[smeenai]

llvm/docs/BuildingADistribution.rst

129

@beanz While you're in a documentation writing mood, I think you'd mentioned wanting to write up tips on creating good PGO sample files and getting good profiling data? :D

130

I think "but" would read better than "however" here.

204

Nit: semicolon instead of comma here.

LLVM_INSTALL_TOOLCHAIN_ONLY also prevents libraries from being installed, right?

Is it worth mentioning LLVM_TOOLCHAIN_TOOLS, which you need to use to get things to actually install if you're using LLVM_INSTALL_TOOLCHAIN_ONLY?

[winksaville]

I'm trying to test the distribution commands from lines 65-67, I first do the cmake:

$ cd ~/prgs/llvm/llvm-project
$ mkdir build
$ cd build
$ cmake -G Ninja -C ../clang/cmake/caches/DistributionExample.cmake ../llvm
loading initial cache file ../clang/cmake/caches/DistributionExample.cmake
-- The C compiler identification is GNU 8.3.0
-- The CXX compiler identification is GNU 8.3.0
-- The ASM compiler identification is GNU
-- Found assembler: /usr/bin/cc
...
-- Performing Test HAVE_STEADY_CLOCK
-- Performing Test HAVE_STEADY_CLOCK -- success
-- Configuring done
-- Generating done
-- Build files have been written to: /home/wink/prgs/llvm/llvm-project/build

That succeeded, then I try the nina command but that fails:

$ ninja stage2-distribution
ninja: error: unknown target 'stage2-distribution'

I then check the ninja targets but there are no stage or distribution targets:

$ ninja -t targets | grep stage
$ ninja -t targets | grep distribution
$ 

What have I done wrong?

[winksaville]

What have I done wrong?

One thing I apparently did wrong was not supply LLVM_ENABLE_PROJECTS so
I added that and CMAKE_INSTALL_PREFIX:

$ cmake ../llvm -G Ninja -C ../clang/cmake/caches/DistributionExample.cmake -DLLVM_ENABLE_PROJECTS=clang -DCMAKE_INSTALL_PREFIX=/home/wink/local-dist

With there is now a stage2-distribution and it started compiling but eventually failed:

++ ninja stage2-distribution -j11 -v
[1/1999] /usr/bin/c++  -DGTEST_HAS_RTTI=0 -D_GNU_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS -Ilib/Support -I/home/wink/prgs/llvm/llvm-project-2/llvm/lib/Support -I/usr/include/libxml2 -Iinclude -I/home/wink/prgs/llvm/llvm-project-2/llvm/include -fPIC -fvisibility-inlines-hidden -Werror=date-time -std=c++11 -Wall -Wextra -Wno-unused-parameter -Wwrite-strings -Wcast-qual -Wno-missing-field-initializers -pedantic -Wno-long-long -Wimplicit-fallthrough -Wno-maybe-uninitialized -Wno-class-memaccess -Wno-noexcept-type -Wdelete-non-virtual-dtor -Wno-comment -fdiagnostics-color -ffunction-sections -fdata-sections -O3 -DNDEBUG    -fno-exceptions -fno-rtti -MD -MT lib/Support/CMakeFiles/LLVMSupport.dir/Atomic.cpp.o -MF lib/Support/CMakeFiles/LLVMSupport.dir/Atomic.cpp.o.d -o lib/Support/CMakeFiles/LLVMSupport.dir/Atomic.cpp.o -c /home/wink/prgs/llvm/llvm-project-2/llvm/lib/Support/Atomic.cpp
...

[1997/1999] cd /home/wink/prgs/llvm/llvm-project-2/build-dist/tools/clang/stage2-bins && /usr/bin/cmake -DCMAKE_INSTALL_PREFIX=/home/wink/local-dist -C /home/wink/prgs/llvm/llvm-project-2/clang/cmake/caches/DistributionExample-stage2.cmake -DLLVM_ENABLE_LTO=ON -DLLVM_EXTERNAL_CLANG_SOURCE_DIR=/home/wink/prgs/llvm/llvm-project-2/llvm/../clang -DPACKAGE_VERSION=9.0.0svn -DPACKAGE_VENDOR=LLVM.org -DLLVM_VERSION_MAJOR=9 -DLLVM_VERSION_MINOR=0 -DLLVM_VERSION_PATCH=0 -DCLANG_VERSION_MAJOR=9 -DCLANG_VERSION_MINOR=0 -DCLANG_VERSION_PATCHLEVEL=0 -DLLVM_VERSION_SUFFIX=svn -DLLVM_BINUTILS_INCDIR= -DCLANG_REPOSITORY_STRING= -DCMAKE_MAKE_PROGRAM=/usr/bin/ninja -DLLVM_ENABLE_PROJECTS=clang -DCLANG_STAGE=stage2 -DCMAKE_CXX_COMPILER=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang++ -DCMAKE_C_COMPILER=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang -DCMAKE_ASM_COMPILER=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang -DCMAKE_ASM_COMPILER_ID=Clang -DCMAKE_AR=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/llvm-ar -DCMAKE_RANLIB=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/llvm-ranlib -GNinja /home/wink/prgs/llvm/llvm-project-2/llvm && /usr/bin/cmake -E touch /home/wink/prgs/llvm/llvm-project-2/build-dist/tools/clang/stage2-stamps//stage2-configure
loading initial cache file /home/wink/prgs/llvm/llvm-project-2/clang/cmake/caches/DistributionExample-stage2.cmake
-- The C compiler identification is Clang 9.0.0
-- The CXX compiler identification is Clang 9.0.0
-- The ASM compiler identification is Clang
-- Found assembler: /home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang
-- Check for working C compiler: /home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang
-- Check for working C compiler: /home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang -- works
...
CMake Error at CMakeLists.txt:1108 (message):
  Specified distribution component 'builtins' doesn't have a target


CMake Error at CMakeLists.txt:1114 (message):
  Specified distribution component 'builtins' doesn't have an install target


CMake Error at CMakeLists.txt:1120 (message):
  Specified distribution component 'builtins' doesn't have an
  install-stripped target.  Its installation target creation should be
  changed to use add_llvm_install_targets, or you should manually create the
  'install-builtins-stripped' target.


CMake Error at CMakeLists.txt:1108 (message):
  Specified distribution component 'runtimes' doesn't have a target


CMake Error at CMakeLists.txt:1114 (message):
  Specified distribution component 'runtimes' doesn't have an install target


CMake Error at CMakeLists.txt:1120 (message):
  Specified distribution component 'runtimes' doesn't have an
  install-stripped target.  Its installation target creation should be
  changed to use add_llvm_install_targets, or you should manually create the
  'install-runtimes-stripped' target.


-- Failed to find LLVM FileCheck
...
-- Performing Test HAVE_STEADY_CLOCK
-- Performing Test HAVE_STEADY_CLOCK
-- Performing Test HAVE_STEADY_CLOCK -- failed to compile
-- Configuring incomplete, errors occurred!
See also "/home/wink/prgs/llvm/llvm-project-2/build-dist/tools/clang/stage2-bins/CMakeFiles/CMakeOutput.log".
See also "/home/wink/prgs/llvm/llvm-project-2/build-dist/tools/clang/stage2-bins/CMakeFiles/CMakeError.log".
FAILED: tools/clang/stage2-stamps/stage2-configure 
cd /home/wink/prgs/llvm/llvm-project-2/build-dist/tools/clang/stage2-bins && /usr/bin/cmake -DCMAKE_INSTALL_PREFIX=/home/wink/local-dist -C /home/wink/prgs/llvm/llvm-project-2/clang/cmake/caches/DistributionExample-stage2.cmake -DLLVM_ENABLE_LTO=ON -DLLVM_EXTERNAL_CLANG_SOURCE_DIR=/home/wink/prgs/llvm/llvm-project-2/llvm/../clang -DPACKAGE_VERSION=9.0.0svn -DPACKAGE_VENDOR=LLVM.org -DLLVM_VERSION_MAJOR=9 -DLLVM_VERSION_MINOR=0 -DLLVM_VERSION_PATCH=0 -DCLANG_VERSION_MAJOR=9 -DCLANG_VERSION_MINOR=0 -DCLANG_VERSION_PATCHLEVEL=0 -DLLVM_VERSION_SUFFIX=svn -DLLVM_BINUTILS_INCDIR= -DCLANG_REPOSITORY_STRING= -DCMAKE_MAKE_PROGRAM=/usr/bin/ninja -DLLVM_ENABLE_PROJECTS=clang -DCLANG_STAGE=stage2 -DCMAKE_CXX_COMPILER=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang++ -DCMAKE_C_COMPILER=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang -DCMAKE_ASM_COMPILER=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/clang -DCMAKE_ASM_COMPILER_ID=Clang -DCMAKE_AR=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/llvm-ar -DCMAKE_RANLIB=/home/wink/prgs/llvm/llvm-project-2/build-dist/./bin/llvm-ranlib -GNinja /home/wink/prgs/llvm/llvm-project-2/llvm && /usr/bin/cmake -E touch /home/wink/prgs/llvm/llvm-project-2/build-dist/tools/clang/stage2-stamps//stage2-configure
ninja: build stopped: subcommand failed.G

So I'm guessing I need to "enable more projects" trying "clang-tools-extra-compiler-rt;libclc;libcxx;libcxxabi;libunwind" now.

[beanz]

@winksaville, sorry those cache files pre-date the monorepo, and they haven’t been updated to support it. I will try and get a patch to update them today.

[winksaville]

In D62040#1507831, @beanz wrote:

@winksaville, sorry those cache files pre-date the monorepo, and they haven’t been updated to support it. I will try and get a patch to update them today.

Thanks!

[beanz]

@winksaville I just committed an update to the DistributionExamples a minute ago that should get them working as long as you aren't using a Darwin host. If you are using a Darwin host you need D62155 as well.

[winksaville]

In D62040#1508937, @beanz wrote:

@winksaville I just committed an update to the DistributionExamples a minute ago that should get them working as long as you aren't using a Darwin host. If you are using a Darwin host you need D62155 as well.

Txs, trying it now.

[beanz]

Updates based on feedback from @smeenai

[beanz]

This has had plenty of time to percolate, so I'm going to land it shorty. Any additional feedback we can incorporate in follow-up patches.

llvm/docs/BuildingADistribution.rst

+===============================
+Building a Distribution of LLVM
+===============================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document is geared toward people who want to build and package LLVM and any
+combination of LLVM sub-project tools for distribution. This document covers
+useful features of the LLVM build system as well as best practices and general
+information about packaging LLVM.
+
+If you are new to CMake you may find the :doc:`CMake` or :doc:`CMakePrimer`
+documentation useful. Some of the things covered in this document are the inner
+workings of the builds described in the :doc:`AdvancedBuilds` document.
+
+General Distribution Guidance
+=============================
+
+When building a distribution of a compiler it is generally advised to perform a
+bootstrap build of the compiler. That means building a "stage 1" compiler with
+your host toolchain, then building the "stage 2" compiler using the "stage 1"
+compiler. This is done so that the compiler you distribute benefits from all the
+bug fixes, performance optimizations and general improvements provided by the
+new compiler.
+
+In deciding how to build your distribution there are a few trade-offs that you
+will need to evaluate. The big two are:
+
+#. Compile time of the distribution against performance of the built compiler
+
+#. Binary size of the distribution against performance of the built compiler
+
+The guidance for maximizing performance of the generated compiler is to use LTO,
+PGO, and statically link everything. This will result in an overall larger
+distribution, and it will take longer to generate, but it provides the most
+opportunity for the compiler to optimize.
+
+The guidance for minimizing distribution size is to dynamically link LLVM and
+Clang libraries into the tools to reduce code duplication. This will come at a
+substantial performance penalty to the generated binary both because it reduces
+optimization opportunity, and because dynamic linking requires resolving symbols
+at process launch time, which can be very slow for C++ code.
+
+.. _shared_libs:
+
+.. warning::
+  One very important note: Distributions should never be built using the
+  *BUILD_SHARED_LIBS* CMake option. That option exists for optimizing developer
+  workflow only. Due to design and implementation decisions, LLVM relies on
+  global data which can end up being duplicated across shared libraries
+  resulting in bugs. As such this is not a safe way to distribute LLVM or
+  LLVM-based tools.
+
+The simplest example of building a distribution with reasonable performance is
+captured in the DistributionExample CMake cache file located at
+clang/cmake/caches/DistributionExample.cmake. The following command will perform
+and install the distribution build:
+
+.. code-block:: console
+
+  $ cmake -G Ninja -C <path to clang>/cmake/caches/DistributionExample.cmake <path to LLVM source>
+  $ ninja stage2-distribution
+  $ ninja stage2-install-distribution
+
+Difference between ``install`` and ``install-distribution``
+-----------------------------------------------------------
+
+One subtle but important thing to note is the difference between the ``install``
+and ``install-distribution`` targets. The ``install`` target is expected to
+install every part of LLVM that your build is configured to generate except the
+LLVM testing tools. Alternatively the ``install-distribution`` target, which is
+recommended for building distributions, only installs specific parts of LLVM as
+specified at configuration time by *LLVM_DISTRIBUTION_COMPONENTS*.
+
+Additionally by default the ``install`` target will install the LLVM testing
+tools as the public tools. This can be changed well by setting
+*LLVM_INSTALL_TOOLCHAIN_ONLY* to ``On``. The LLVM tools are intended for
+development and testing of LLVM, and should only be included in distributions
+that support LLVM development.
+
+When building with *LLVM_DISTRIBUTION_COMPONENTS* the build system also
+generates a ``distribution`` target which builds all the components specified in
+the list. This is a convenience build target to allow building just the
+distributed pieces without needing to build all configured targets.
+
+Special Notes for Library-only Distributions
+--------------------------------------------
+
+One of the most powerful features of LLVM is its library-first design mentality
+and the way you can compose a wide variety of tools using different portions of
+LLVM. Even in this situation using *BUILD_SHARED_LIBS* is not supported. If you
+want to distribute LLVM as a shared library for use in a tool, the recommended
+method is using *LLVM_BUILD_LLVM_DYLIB*, and you can use *LLVM_DYLIB_COMPONENTS*
+to configure which LLVM components are part of libLLVM.
+
+Options for Optimizing LLVM
+===========================
+
+There are four main build optimizations that our CMake build system supports.
+When performing a bootstrap build it is not beneficial to do anything other than
+setting *CMAKE_BUILD_TYPE* to ``Release`` for the stage-1 compiler. This is
+because the more intensive optimizations are expensive to perform and the
+stage-1 compiler is thrown away. All of the further options described should be
+set on the stage-2 compiler either using a CMake cache file, or by prefixing the
+option with *BOOTSTRAP_*.
+
+The first and simplest to use is the compiler optimization level by setting the
+*CMAKE_BUILD_TYPE* option. The main values of interest are ``Release`` or
+``RelWithDebInfo``. By default the ``Release`` option uses the ``-O3``
+optimization level, and ``RelWithDebInfo`` uses ``-O2``. If you want to generate
+debug information and use ``-O3`` you can override the
+*CMAKE_<LANG>_FLAGS_RELWITHDEBINFO* option for C and CXX.
+DistributionExample.cmake does this.
+
+Another easy to use option is Link-Time-Optimization. You can set the
+*LLVM_ENABLE_LTO* option on your stage-2 build to ``Thin`` or ``Full`` to enable
+building LLVM with LTO. These options will significantly increase link time of
+the binaries in the distribution, but it will create much faster binaries. This
+option should not be used if your distribution includes static archives, as the
+objects inside the archive will be LLVM bitcode, which is not portable.
+
+The :doc:`AdvancedBuilds` documentation describes the built-in tooling for
+generating LLVM profiling information to drive Profile-Guided-Optimization. The
+in-tree profiling tests are very limited, and generating the profile takes a
+significant amount of time, but it can result in a significant improvement in
+the performance of the generated binaries.
+
+In addition to PGO profiling we also have limited support in-tree for generating
+linker order files. These files provide the linker with a suggested ordering for
+functions in the final binary layout. This can measurably speed up clang by
+physically grouping functions that are called temporally close to eachother. The
+current tooling is only available on Darwin systems with ``dtrace(1)``. It is
+worth noting that dtrace is non-deterministic, and so the order file generation
+using dtrace is also non-deterministic.
+
+Options for Reducing Size
+=========================
+
+.. warning::
+  Any steps taken to reduce the binary size will come at a cost of runtime
+  performance in the generated binaries.
+
+The simplest and least significant way to reduce binary size is to set the
+*CMAKE_BUILD_TYPE* variable to ``MinSizeRel``, which will set the compiler
+optimization level to ``-Os`` which optimizes for binary size. This will have
+both the least benefit to size and the least impact on performance.
+
+The most impactful way to reduce binary size is to dynamically link LLVM into
+all the tools. This reduces code size by decreasing duplication of common code
+between the LLVM-based tools. This can be done by setting the following two
+CMake options to ``On``: *LLVM_BUILD_LLVM_DYLIB* and *LLVM_LINK_LLVM_DYLIB*.
+
+.. warning::
+  Distributions should never be built using the *BUILD_SHARED_LIBS* CMake
+  option. (:ref:`See the warning above for more explanation <shared_libs>`.).
+
+Relevant CMake Options
+======================
+
+This section provides documentation of the CMake options that are intended to
+help construct distributions. This is not an exhaustive list, and many
+additional options are documented in the :doc:`CMake` page. Some key options
+that are already documented include: *LLVM_TARGETS_TO_BUILD*,
+*LLVM_ENABLE_PROJECTS*, *LLVM_BUILD_LLVM_DYLIB*, and *LLVM_LINK_LLVM_DYLIB*.
+
+**LLVM_ENABLE_RUNTIMES**:STRING
+  When building a distribution that includes LLVM runtime projects (i.e. libcxx,
+  compiler-rt, libcxxabi, libunwind...), it is important to build those projects
+  with the just-built compiler.
+
+**LLVM_DISTRIBUTION_COMPONENTS**:STRING
+  This variable can be set to a semi-colon separated list of LLVM build system
+  components to install. All LLVM-based tools are components, as well as most
+  of the libraries and runtimes. Component names match the names of the build
+  system targets.
+
+**LLVM_RUNTIME_DISTRIBUTION_COMPONENTS**:STRING
+  This variable can be set to a semi-colon separated list of runtime library
+  components. This is used in conjunction with *LLVM_ENABLE_RUNTIMES* to specify
+  components of runtime libraries that you want to include in your distribution.
+  Just like with *LLVM_DISTRIBUTION_COMPONENTS*, component names match the names
+  of the build system targets.
+
+**LLVM_DYLIB_COMPONENTS**:STRING
+  This variable can be set to a semi-colon separated name of LLVM library
+  components. LLVM library components are either library names with the LLVM
+  prefix removed (i.e. Support, Demangle...), LLVM target names, or special
+  purpose component names. The special purpose component names are:
+  
+  #. ``all`` - All LLVM available component libraries
+  #. ``Native`` - The LLVM target for the Native system
+  #. ``AllTargetsAsmPrinters`` - All the included target ASM printers libraries
+  #. ``AllTargetsAsmParsers`` - All the included target ASM parsers libraries
+  #. ``AllTargetsDescs`` - All the included target descriptions libraries
+  #. ``AllTargetsDisassemblers`` - All the included target dissassemblers libraries
+  #. ``AllTargetsInfos`` - All the included target info libraries
+
+**LLVM_INSTALL_TOOLCHAIN_ONLY**:BOOL
+  This option defaults to ``Off``: when set to ``On`` it removes many of the
+  LLVM development and testing tools as well as component libraries from the
+  default ``install`` target. Including the development tools is not recommended
+  for distributions as many of the LLVM tools are only intended for development
+  and testing use.

llvm/docs/index.rst

.. toctree::
    Frontend/PerformanceTips
    MCJITDesignAndImplementation
    ORCv2DesignAndImplementation
    CodeOfConduct
    CompileCudaWithLLVM
    ReportingGuide
    Benchmarking
    Docker
+   BuildingADistribution
 
 :doc:`GettingStarted`
    Discusses how to get up and running quickly with the LLVM infrastructure.
    Everything from unpacking and compilation of the distribution to execution
    of some tools.
 
 :doc:`CMake`
    An addendum to the main Getting Started guide for those using the `CMake

 
 :doc:`Frontend/PerformanceTips`
    A collection of tips for frontend authors on how to generate IR
    which LLVM is able to effectively optimize.
 
 :doc:`Docker`
    A reference for using Dockerfiles provided with LLVM.
 
+:doc:`BuildingADistribution`
+  A best-practices guide for using LLVM's CMake build system to package and
+  distribute LLVM-based tools.
+
 
 Programming Documentation
 =========================
 
 For developers of applications which use LLVM as a library.
 
 .. toctree::
    :hidden: