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