docs/LLVMBuild.html

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