docs: Sphinxify LLVMBuild documentation.

git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@168348 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 325 insertions, 0 deletions

diff --git a/docs/LLVMBuild.rst b/docs/LLVMBuild.rst
new file mode 100644
index 0000000000..d9215dd8eb
--- /dev/null
+++ b/docs/LLVMBuild.rst
@@ -0,0 +1,325 @@
+===============
+LLVMBuild Guide
+===============
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document describes the ``LLVMBuild`` organization and files which
+we use to describe parts of the LLVM ecosystem. For description of
+specific LLVMBuild related tools, please see the command guide.
+
+LLVM is designed to be a modular set of libraries which can be flexibly
+mixed together in order to build a variety of tools, like compilers,
+JITs, custom code generators, optimization passes, interpreters, and so
+on. Related projects in the LLVM system like Clang and LLDB also tend to
+follow this philosophy.
+
+In order to support this usage style, LLVM has a fairly strict structure
+as to how the source code and various components are organized. The
+``LLVMBuild.txt`` files are the explicit specification of that
+structure, and are used by the build systems and other tools in order to
+develop the LLVM project.
+
+Project Organization
+====================
+
+The source code for LLVM projects using the LLVMBuild system (LLVM,
+Clang, and LLDB) is organized into *components*, which define the
+separate pieces of functionality that make up the project. These
+projects may consist of many libraries, associated tools, build tools,
+or other utility tools (for example, testing tools).
+
+For the most part, the project contents are organized around defining
+one main component per each subdirectory. Each such directory contains
+an ``LLVMBuild.txt`` which contains the component definitions.
+
+The component descriptions for the project as a whole are automatically
+gathered by the LLVMBuild tools. The tools automatically traverse the
+source directory structure to find all of the component description
+files. NOTE: For performance/sanity reasons, we only traverse into
+subdirectories when the parent itself contains an ``LLVMBuild.txt``
+description file.
+
+Build Integration
+=================
+
+The LLVMBuild files themselves are just a declarative way to describe
+the project structure. The actual building of the LLVM project is
+handled by another build system (currently we support both
+:doc:`Makefiles <MakefileGuide>` and :doc:`CMake <CMake>`).
+
+The build system implementation will load the relevant contents of the
+LLVMBuild files and use that to drive the actual project build.
+Typically, the build system will only need to load this information at
+"configure" time, and use it to generative native information. Build
+systems will also handle automatically reconfiguring their information
+when the contents of the ``LLVMBuild.txt`` files change.
+
+Developers generally are not expected to need to be aware of the details
+of how the LLVMBuild system is integrated into their build. Ideally,
+LLVM developers who are not working on the build system would only ever
+need to modify the contents of the ``LLVMBuild.txt`` description files
+(although we have not reached this goal yet).
+
+For more information on the utility tool we provide to help interfacing
+with the build system, please see the :doc:`llvm-build
+<CommandGuide/llvm-build>` documentation.
+
+Component Overview
+==================
+
+As mentioned earlier, LLVM projects are organized into logical
+*components*. Every component is typically grouped into its own
+subdirectory. Generally, a component is organized around a coherent
+group of sources which have some kind of clear API separation from other
+parts of the code.
+
+LLVM primarily uses the following types of components:
+
+- *Libraries* - Library components define a distinct API which can be
+  independently linked into LLVM client applications. Libraries typically
+  have private and public header files, and may specify a link of required
+  libraries that they build on top of.
+- *Build Tools* - Build tools are applications which are designed to be run
+  as part of the build process (typically to generate other source files).
+  Currently, LLVM uses one main build tool called :doc:`TableGen
+  <TableGenFundamentals>` to generate a variety of source files.
+- *Tools* - Command line applications which are built using the LLVM
+  component libraries. Most LLVM tools are small and are primarily
+  frontends to the library interfaces.
+
+Components are described using ``LLVMBuild.txt`` files in the directories
+that define the component. See the `LLVMBuild Format Reference`_ section
+for information on the exact format of these files.
+
+LLVMBuild Format Reference
+==========================
+
+LLVMBuild files are written in a simple variant of the INI or configuration
+file format (`Wikipedia entry`_). The format defines a list of sections
+each of which may contain some number of properties. A simple example of
+the file format is below:
+
+.. _Wikipedia entry: http://en.wikipedia.org/wiki/INI_file
+
+.. code-block:: ini
+
+   ; Comments start with a semi-colon.
+
+   ; Sections are declared using square brackets.
+   [component_0]
+
+   ; Properties are declared using '=' and are contained in the previous section.
+   ;
+   ; We support simple string and boolean scalar values and list values, where
+   ; items are separated by spaces. There is no support for quoting, and so
+   ; property values may not contain spaces.
+   property_name = property_value
+   list_property_name = value_1 value_2 ... value_n
+   boolean_property_name = 1 (or 0)
+
+LLVMBuild files are expected to define a strict set of sections and
+properties. An typical component description file for a library
+component would look typically look like the following example:
+
+.. code-block:: ini
+
+   [component_0]
+   type = Library
+   name = Linker
+   parent = Libraries
+   required_libraries = Archive BitReader Core Support TransformUtils
+
+A full description of the exact sections and properties which are
+allowed follows.
+
+Each file may define exactly one common component, named ``common``. The
+common component may define the following properties:
+
+-  ``subdirectories`` **[optional]**
+
+   If given, a list of the names of the subdirectories from the current
+   subpath to search for additional LLVMBuild files.
+
+Each file may define multiple components. Each component is described by a
+section who name starts with ``component``. The remainder of the section
+name is ignored, but each section name must be unique. Typically components
+are just number in order for files with multiple components
+(``component_0``, ``component_1``, and so on).
+
+.. warning::
+
+   Section names not matching this format (or the ``common`` section) are
+   currently unused and are disallowed.
+
+Every component is defined by the properties in the section. The exact
+list of properties that are allowed depends on the component type.
+Components **may not** define any properties other than those expected
+by the component type.
+
+Every component must define the following properties:
+
+-  ``type`` **[required]**
+
+   The type of the component. Supported component types are detailed
+   below. Most components will define additional properties which may be
+   required or optional.
+
+-  ``name`` **[required]**
+
+   The name of the component. Names are required to be unique across the
+   entire project.
+
+-  ``parent`` **[required]**
+
+   The name of the logical parent of the component. Components are
+   organized into a logical tree to make it easier to navigate and
+   organize groups of components. The parents have no semantics as far
+   as the project build is concerned, however. Typically, the parent
+   will be the main component of the parent directory.
+
+   Components may reference the root pseudo component using ``$ROOT`` to
+   indicate they should logically be grouped at the top-level.
+
+Components may define the following properties:
+
+-  ``dependencies`` **[optional]**
+
+   If specified, a list of names of components which *must* be built
+   prior to this one. This should only be exactly those components which
+   produce some tool or source code required for building the component.
+
+   .. note::
+
+      ``Group`` and ``LibraryGroup`` components have no semantics for the
+      actual build, and are not allowed to specify dependencies.
+
+The following section lists the available component types, as well as
+the properties which are associated with that component.
+
+-  ``type = Group``
+
+   Group components exist purely to allow additional arbitrary structuring
+   of the logical components tree. For example, one might define a
+   ``Libraries`` group to hold all of the root library components.
+
+   ``Group`` components have no additionally properties.
+
+-  ``type = Library``
+
+   Library components define an individual library which should be built
+   from the source code in the component directory.
+
+   Components with this type use the following properties:
+
+   -  ``library_name`` **[optional]**
+
+      If given, the name to use for the actual library file on disk. If
+      not given, the name is derived from the component name itself.
+
+   -  ``required_libraries`` **[optional]**
+
+      If given, a list of the names of ``Library`` or ``LibraryGroup``
+      components which must also be linked in whenever this library is
+      used. That is, the link time dependencies for this component. When
+      tools are built, the build system will include the transitive closure
+      of all ``required_libraries`` for the components the tool needs.
+
+   -  ``add_to_library_groups`` **[optional]**
+
+      If given, a list of the names of ``LibraryGroup`` components which
+      this component is also part of. This allows nesting groups of
+      components.  For example, the ``X86`` target might define a library
+      group for all of the ``X86`` components. That library group might
+      then be included in the ``all-targets`` library group.
+
+   -  ``installed`` **[optional]** **[boolean]**
+
+      Whether this library is installed. Libraries that are not installed
+      are only reported by ``llvm-config`` when it is run as part of a
+      development directory.
+
+-  ``type = LibraryGroup``
+
+   ``LibraryGroup`` components are a mechanism to allow easy definition of
+   useful sets of related components. In particular, we use them to easily
+   specify things like "all targets", or "all assembly printers".
+
+   Components with this type use the following properties:
+
+   -  ``required_libraries`` **[optional]**
+
+      See the ``Library`` type for a description of this property.
+
+   -  ``add_to_library_groups`` **[optional]**
+
+      See the ``Library`` type for a description of this property.
+
+-  ``type = TargetGroup``
+
+   ``TargetGroup`` components are an extension of ``LibraryGroup``\s,
+   specifically for defining LLVM targets (which are handled specially in a
+   few places).
+
+   The name of the component should always be the name of the target.
+
+   Components with this type use the ``LibraryGroup`` properties in
+   addition to:
+
+   -  ``has_asmparser`` **[optional]** **[boolean]**
+
+      Whether this target defines an assembly parser.
+
+   -  ``has_asmprinter`` **[optional]** **[boolean]**
+
+      Whether this target defines an assembly printer.
+
+   -  ``has_disassembler`` **[optional]** **[boolean]**
+
+      Whether this target defines a disassembler.
+
+   -  ``has_jit`` **[optional]** **[boolean]**
+
+      Whether this target supports JIT compilation.
+
+-  ``type = Tool``
+
+   ``Tool`` components define standalone command line tools which should be
+   built from the source code in the component directory and linked.
+
+   Components with this type use the following properties:
+
+   -  ``required_libraries`` **[optional]**
+
+      If given, a list of the names of ``Library`` or ``LibraryGroup``
+      components which this tool is required to be linked with.
+
+      .. note::
+
+         The values should be the component names, which may not always
+         match up with the actual library names on disk.
+
+      Build systems are expected to properly include all of the libraries
+      required by the linked components (i.e., the transitive closure of
+      ``required_libraries``).
+
+      Build systems are also expected to understand that those library
+      components must be built prior to linking -- they do not also need
+      to be listed under ``dependencies``.
+
+-  ``type = BuildTool``
+
+   ``BuildTool`` components are like ``Tool`` components, except that the
+   tool is supposed to be built for the platform where the build is running
+   (instead of that platform being targetted). Build systems are expected
+   to handle the fact that required libraries may need to be built for
+   multiple platforms in order to be able to link this tool.
+
+   ``BuildTool`` components currently use the exact same properties as
+   ``Tool`` components, the type distinction is only used to differentiate
+   what the tool is built for.
+