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 (currently we support both 53:doc:`Makefiles <MakefileGuide>` and :doc:`CMake <CMake>`). 54 55The build system implementation will load the relevant contents of the 56LLVMBuild files and use that to drive the actual project build. 57Typically, the build system will only need to load this information at 58"configure" time, and use it to generative native information. Build 59systems will also handle automatically reconfiguring their information 60when the contents of the ``LLVMBuild.txt`` files change. 61 62Developers generally are not expected to need to be aware of the details 63of how the LLVMBuild system is integrated into their build. Ideally, 64LLVM developers who are not working on the build system would only ever 65need to modify the contents of the ``LLVMBuild.txt`` description files 66(although we have not reached this goal yet). 67 68For more information on the utility tool we provide to help interfacing 69with the build system, please see the :doc:`llvm-build 70<CommandGuide/llvm-build>` documentation. 71 72Component Overview 73================== 74 75As mentioned earlier, LLVM projects are organized into logical 76*components*. Every component is typically grouped into its own 77subdirectory. Generally, a component is organized around a coherent 78group of sources which have some kind of clear API separation from other 79parts of the code. 80 81LLVM 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 95Components are described using ``LLVMBuild.txt`` files in the directories 96that define the component. See the `LLVMBuild Format Reference`_ section 97for information on the exact format of these files. 98 99LLVMBuild Format Reference 100========================== 101 102LLVMBuild files are written in a simple variant of the INI or configuration 103file format (`Wikipedia entry`_). The format defines a list of sections 104each of which may contain some number of properties. A simple example of 105the 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 125LLVMBuild files are expected to define a strict set of sections and 126properties. A typical component description file for a library 127component 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 137A full description of the exact sections and properties which are 138allowed follows. 139 140Each file may define exactly one common component, named ``common``. The 141common 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 148Each file may define multiple components. Each component is described by a 149section who name starts with ``component``. The remainder of the section 150name is ignored, but each section name must be unique. Typically components 151are 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 159Every component is defined by the properties in the section. The exact 160list of properties that are allowed depends on the component type. 161Components **may not** define any properties other than those expected 162by the component type. 163 164Every 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 188Components 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 201The following section lists the available component types, as well as 202the 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 326