1=============== 2LLVMBuild Guide 3=============== 4 5.. contents:: 6 :local: 7 8Introduction 9============ 10 11This document describes the ``LLVMBuild`` organization and files which 12we use to describe parts of the LLVM ecosystem. For description of 13specific LLVMBuild related tools, please see the command guide. 14 15LLVM is designed to be a modular set of libraries which can be flexibly 16mixed together in order to build a variety of tools, like compilers, 17JITs, custom code generators, optimization passes, interpreters, and so 18on. Related projects in the LLVM system like Clang and LLDB also tend to 19follow this philosophy. 20 21In order to support this usage style, LLVM has a fairly strict structure 22as to how the source code and various components are organized. The 23``LLVMBuild.txt`` files are the explicit specification of that 24structure, and are used by the build systems and other tools in order to 25develop the LLVM project. 26 27Project Organization 28==================== 29 30The source code for LLVM projects using the LLVMBuild system (LLVM, 31Clang, and LLDB) is organized into *components*, which define the 32separate pieces of functionality that make up the project. These 33projects may consist of many libraries, associated tools, build tools, 34or other utility tools (for example, testing tools). 35 36For the most part, the project contents are organized around defining 37one main component per each subdirectory. Each such directory contains 38an ``LLVMBuild.txt`` which contains the component definitions. 39 40The component descriptions for the project as a whole are automatically 41gathered by the LLVMBuild tools. The tools automatically traverse the 42source directory structure to find all of the component description 43files. NOTE: For performance/sanity reasons, we only traverse into 44subdirectories when the parent itself contains an ``LLVMBuild.txt`` 45description file. 46 47Build Integration 48================= 49 50The LLVMBuild files themselves are just a declarative way to describe 51the project structure. The actual building of the LLVM project is 52handled by another build system (See: :doc:`CMake <CMake>`). 53 54The build system implementation will load the relevant contents of the 55LLVMBuild files and use that to drive the actual project build. 56Typically, the build system will only need to load this information at 57"configure" time, and use it to generative native information. Build 58systems will also handle automatically reconfiguring their information 59when the contents of the ``LLVMBuild.txt`` files change. 60 61Developers generally are not expected to need to be aware of the details 62of how the LLVMBuild system is integrated into their build. Ideally, 63LLVM developers who are not working on the build system would only ever 64need to modify the contents of the ``LLVMBuild.txt`` description files 65(although we have not reached this goal yet). 66 67For more information on the utility tool we provide to help interfacing 68with the build system, please see the :doc:`llvm-build 69<CommandGuide/llvm-build>` documentation. 70 71Component Overview 72================== 73 74As mentioned earlier, LLVM projects are organized into logical 75*components*. Every component is typically grouped into its own 76subdirectory. Generally, a component is organized around a coherent 77group of sources which have some kind of clear API separation from other 78parts of the code. 79 80LLVM 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 94Components are described using ``LLVMBuild.txt`` files in the directories 95that define the component. See the `LLVMBuild Format Reference`_ section 96for information on the exact format of these files. 97 98LLVMBuild Format Reference 99========================== 100 101LLVMBuild files are written in a simple variant of the INI or configuration 102file format (`Wikipedia entry`_). The format defines a list of sections 103each of which may contain some number of properties. A simple example of 104the 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 124LLVMBuild files are expected to define a strict set of sections and 125properties. A typical component description file for a library 126component 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 136A full description of the exact sections and properties which are 137allowed follows. 138 139Each file may define exactly one common component, named ``common``. The 140common 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 147Each file may define multiple components. Each component is described by a 148section who name starts with ``component``. The remainder of the section 149name is ignored, but each section name must be unique. Typically components 150are 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 158Every component is defined by the properties in the section. The exact 159list of properties that are allowed depends on the component type. 160Components **may not** define any properties other than those expected 161by the component type. 162 163Every 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 187Components 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 200The following section lists the available component types, as well as 201the 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. 324 325