docs/LLVMBuild.rst

   1 ===============
   2 LLVMBuild Guide
   3 ===============
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction
   9 ============
  10
  11 This document describes the ``LLVMBuild`` organization and files which
  12 we use to describe parts of the LLVM ecosystem. For description of
  13 specific LLVMBuild related tools, please see the command guide.
  14
  15 LLVM is designed to be a modular set of libraries which can be flexibly
  16 mixed together in order to build a variety of tools, like compilers,
  17 JITs, custom code generators, optimization passes, interpreters, and so
  18 on. Related projects in the LLVM system like Clang and LLDB also tend to
  19 follow this philosophy.
  20
  21 In order to support this usage style, LLVM has a fairly strict structure
  22 as to how the source code and various components are organized. The
  23 ``LLVMBuild.txt`` files are the explicit specification of that
  24 structure, and are used by the build systems and other tools in order to
  25 develop the LLVM project.
  26
  27 Project Organization
  28 ====================
  29
  30 The source code for LLVM projects using the LLVMBuild system (LLVM,
  31 Clang, and LLDB) is organized into *components*, which define the
  32 separate pieces of functionality that make up the project. These
  33 projects may consist of many libraries, associated tools, build tools,
  34 or other utility tools (for example, testing tools).
  35
  36 For the most part, the project contents are organized around defining
  37 one main component per each subdirectory. Each such directory contains
  38 an ``LLVMBuild.txt`` which contains the component definitions.
  39
  40 The component descriptions for the project as a whole are automatically
  41 gathered by the LLVMBuild tools. The tools automatically traverse the
  42 source directory structure to find all of the component description
  43 files. NOTE: For performance/sanity reasons, we only traverse into
  44 subdirectories when the parent itself contains an ``LLVMBuild.txt``
  45 description file.
  46
  47 Build Integration
  48 =================
  49
  50 The LLVMBuild files themselves are just a declarative way to describe
  51 the project structure. The actual building of the LLVM project is
  52 handled by another build system (See: :doc:`CMake <CMake>`).
  53
  54 The build system implementation will load the relevant contents of the
  55 LLVMBuild files and use that to drive the actual project build.
  56 Typically, the build system will only need to load this information at
  57 "configure" time, and use it to generate native information. Build
  58 systems will also handle automatically reconfiguring their information
  59 when the contents of the ``LLVMBuild.txt`` files change.
  60
  61 Developers generally are not expected to need to be aware of the details
  62 of how the LLVMBuild system is integrated into their build. Ideally,
  63 LLVM developers who are not working on the build system would only ever
  64 need to modify the contents of the ``LLVMBuild.txt`` description files
  65 (although we have not reached this goal yet).
  66
  67 For more information on the utility tool we provide to help interfacing
  68 with the build system, please see the :doc:`llvm-build
  69 <CommandGuide/llvm-build>` documentation.
  70
  71 Component Overview
  72 ==================
  73
  74 As mentioned earlier, LLVM projects are organized into logical
  75 *components*. Every component is typically grouped into its own
  76 subdirectory. Generally, a component is organized around a coherent
  77 group of sources which have some kind of clear API separation from other
  78 parts of the code.
  79
  80 LLVM primarily uses the following types of components:
  81
  82 - *Libraries* - Library components define a distinct API which can be
  83   independently linked into LLVM client applications. Libraries typically
  84   have private and public header files, and may specify a link of required
  85   libraries that they build on top of.
  86 - *Build Tools* - Build tools are applications which are designed to be run
  87   as part of the build process (typically to generate other source files).
  88   Currently, LLVM uses one main build tool called :doc:`TableGen/index`
  89   to generate a variety of source files.
  90 - *Tools* - Command line applications which are built using the LLVM
  91   component libraries. Most LLVM tools are small and are primarily
  92   frontends to the library interfaces.
  93
  94 Components are described using ``LLVMBuild.txt`` files in the directories
  95 that define the component. See the `LLVMBuild Format Reference`_ section
  96 for information on the exact format of these files.
  97
  98 LLVMBuild Format Reference
  99 ==========================
 100
 101 LLVMBuild files are written in a simple variant of the INI or configuration
 102 file format (`Wikipedia entry`_). The format defines a list of sections
 103 each of which may contain some number of properties. A simple example of
 104 the file format is below:
 105
 106 .. _Wikipedia entry: http://en.wikipedia.org/wiki/INI_file
 107
 108 .. code-block:: ini
 109
 110    ; Comments start with a semi-colon.
 111
 112    ; Sections are declared using square brackets.
 113    [component_0]
 114
 115    ; Properties are declared using '=' and are contained in the previous section.
 116    ;
 117    ; We support simple string and boolean scalar values and list values, where
 118    ; items are separated by spaces. There is no support for quoting, and so
 119    ; property values may not contain spaces.
 120    property_name = property_value
 121    list_property_name = value_1 value_2 ... value_n
 122    boolean_property_name = 1 (or 0)
 123
 124 LLVMBuild files are expected to define a strict set of sections and
 125 properties. A typical component description file for a library
 126 component would look like the following example:
 127
 128 .. code-block:: ini
 129
 130    [component_0]
 131    type = Library
 132    name = Linker
 133    parent = Libraries
 134    required_libraries = Archive BitReader Core Support TransformUtils
 135
 136 A full description of the exact sections and properties which are
 137 allowed follows.
 138
 139 Each file may define exactly one common component, named ``common``. The
 140 common component may define the following properties:
 141
 142 -  ``subdirectories`` **[optional]**
 143
 144    If given, a list of the names of the subdirectories from the current
 145    subpath to search for additional LLVMBuild files.
 146
 147 Each file may define multiple components. Each component is described by a
 148 section who name starts with ``component``. The remainder of the section
 149 name is ignored, but each section name must be unique. Typically components
 150 are just number in order for files with multiple components
 151 (``component_0``, ``component_1``, and so on).
 152
 153 .. warning::
 154
 155    Section names not matching this format (or the ``common`` section) are
 156    currently unused and are disallowed.
 157
 158 Every component is defined by the properties in the section. The exact
 159 list of properties that are allowed depends on the component type.
 160 Components **may not** define any properties other than those expected
 161 by the component type.
 162
 163 Every component must define the following properties:
 164
 165 -  ``type`` **[required]**
 166
 167    The type of the component. Supported component types are detailed
 168    below. Most components will define additional properties which may be
 169    required or optional.
 170
 171 -  ``name`` **[required]**
 172
 173    The name of the component. Names are required to be unique across the
 174    entire project.
 175
 176 -  ``parent`` **[required]**
 177
 178    The name of the logical parent of the component. Components are
 179    organized into a logical tree to make it easier to navigate and
 180    organize groups of components. The parents have no semantics as far
 181    as the project build is concerned, however. Typically, the parent
 182    will be the main component of the parent directory.
 183
 184    Components may reference the root pseudo component using ``$ROOT`` to
 185    indicate they should logically be grouped at the top-level.
 186
 187 Components may define the following properties:
 188
 189 -  ``dependencies`` **[optional]**
 190
 191    If specified, a list of names of components which *must* be built
 192    prior to this one. This should only be exactly those components which
 193    produce some tool or source code required for building the component.
 194
 195    .. note::
 196
 197       ``Group`` and ``LibraryGroup`` components have no semantics for the
 198       actual build, and are not allowed to specify dependencies.
 199
 200 The following section lists the available component types, as well as
 201 the properties which are associated with that component.
 202
 203 -  ``type = Group``
 204
 205    Group components exist purely to allow additional arbitrary structuring
 206    of the logical components tree. For example, one might define a
 207    ``Libraries`` group to hold all of the root library components.
 208
 209    ``Group`` components have no additionally properties.
 210
 211 -  ``type = Library``
 212
 213    Library components define an individual library which should be built
 214    from the source code in the component directory.
 215
 216    Components with this type use the following properties:
 217
 218    -  ``library_name`` **[optional]**
 219
 220       If given, the name to use for the actual library file on disk. If
 221       not given, the name is derived from the component name itself.
 222
 223    -  ``required_libraries`` **[optional]**
 224
 225       If given, a list of the names of ``Library`` or ``LibraryGroup``
 226       components which must also be linked in whenever this library is
 227       used. That is, the link time dependencies for this component. When
 228       tools are built, the build system will include the transitive closure
 229       of all ``required_libraries`` for the components the tool needs.
 230
 231    -  ``add_to_library_groups`` **[optional]**
 232
 233       If given, a list of the names of ``LibraryGroup`` components which
 234       this component is also part of. This allows nesting groups of
 235       components.  For example, the ``X86`` target might define a library
 236       group for all of the ``X86`` components. That library group might
 237       then be included in the ``all-targets`` library group.
 238
 239    -  ``installed`` **[optional]** **[boolean]**
 240
 241       Whether this library is installed. Libraries that are not installed
 242       are only reported by ``llvm-config`` when it is run as part of a
 243       development directory.
 244
 245 -  ``type = LibraryGroup``
 246
 247    ``LibraryGroup`` components are a mechanism to allow easy definition of
 248    useful sets of related components. In particular, we use them to easily
 249    specify things like "all targets", or "all assembly printers".
 250
 251    Components with this type use the following properties:
 252
 253    -  ``required_libraries`` **[optional]**
 254
 255       See the ``Library`` type for a description of this property.
 256
 257    -  ``add_to_library_groups`` **[optional]**
 258
 259       See the ``Library`` type for a description of this property.
 260
 261 -  ``type = TargetGroup``
 262
 263    ``TargetGroup`` components are an extension of ``LibraryGroup``\s,
 264    specifically for defining LLVM targets (which are handled specially in a
 265    few places).
 266
 267    The name of the component should always be the name of the target.
 268
 269    Components with this type use the ``LibraryGroup`` properties in
 270    addition to:
 271
 272    -  ``has_asmparser`` **[optional]** **[boolean]**
 273
 274       Whether this target defines an assembly parser.
 275
 276    -  ``has_asmprinter`` **[optional]** **[boolean]**
 277
 278       Whether this target defines an assembly printer.
 279
 280    -  ``has_disassembler`` **[optional]** **[boolean]**
 281
 282       Whether this target defines a disassembler.
 283
 284    -  ``has_jit`` **[optional]** **[boolean]**
 285
 286       Whether this target supports JIT compilation.
 287
 288 -  ``type = Tool``
 289
 290    ``Tool`` components define standalone command line tools which should be
 291    built from the source code in the component directory and linked.
 292
 293    Components with this type use the following properties:
 294
 295    -  ``required_libraries`` **[optional]**
 296
 297       If given, a list of the names of ``Library`` or ``LibraryGroup``
 298       components which this tool is required to be linked with.
 299
 300       .. note::
 301
 302          The values should be the component names, which may not always
 303          match up with the actual library names on disk.
 304
 305       Build systems are expected to properly include all of the libraries
 306       required by the linked components (i.e., the transitive closure of
 307       ``required_libraries``).
 308
 309       Build systems are also expected to understand that those library
 310       components must be built prior to linking -- they do not also need
 311       to be listed under ``dependencies``.
 312
 313 -  ``type = BuildTool``
 314
 315    ``BuildTool`` components are like ``Tool`` components, except that the
 316    tool is supposed to be built for the platform where the build is running
 317    (instead of that platform being targeted). Build systems are expected
 318    to handle the fact that required libraries may need to be built for
 319    multiple platforms in order to be able to link this tool.
 320
 321    ``BuildTool`` components currently use the exact same properties as
 322    ``Tool`` components, the type distinction is only used to differentiate
 323    what the tool is built for.