Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 19f18be449268605ea210e68b02220a0e7bd0c15 / . / docs / LLVMBuild.html
blob: b06946743b8aef67f64773b9a7d4f338b6cd0667 [file] [log] [blame]
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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
47place 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>
Daniel Dunbar2adb2a52011-11-03 17:56:24 +0000[diff] [blame]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>
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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<!-- *********************************************************************** -->
Daniel Dunbarc352caf2011-11-10 00:49:51 +0000[diff] [blame]137<h2><a name="formatreference">LLVMBuild Format Reference</a></h2>
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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>
Daniel Dunbare5609ab2011-12-12 22:45:59 +0000[diff] [blame]150[component_0]
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]151
152<i>; Properties are declared using '=' and are contained in the previous section.
153;
Daniel Dunbarc352caf2011-11-10 00:49:51 +0000[diff] [blame]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>
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]157property_name = property_value
158list_property_name = value_1 value_2 <em>...</em> value_n
Daniel Dunbarc352caf2011-11-10 00:49:51 +0000[diff] [blame]159boolean_property_name = 1 <em>(or 0)</em>
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]160</pre>
161 </div>
162
Daniel Dunbare5609ab2011-12-12 22:45:59 +0000[diff] [blame]163 <p>LLVMBuild files are expected to define a strict set of sections and
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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]
169type = Library
170name = Linker
171parent = Libraries
172required_libraries = Archive BitReader Core Support TransformUtils
173</pre>
174 </div class="doc_code">
175
176 <p>A full description of the exact sections and properties which are allowed
177 follows.</p>
178
Daniel Dunbare5609ab2011-12-12 22:45:59 +0000[diff] [blame]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
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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
Daniel Dunbare5609ab2011-12-12 22:45:59 +0000[diff] [blame]193 <p><b>Section names not matches this format (or the "common" section) are
194 currently unused and are disallowed.</b></p>
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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
Daniel Dunbarc352caf2011-11-10 00:49:51 +0000[diff] [blame]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>
Daniel Dunbar5ed55062011-11-11 00:23:56 +0000[diff] [blame]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>
Daniel Dunbarc352caf2011-11-10 00:49:51 +0000[diff] [blame]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
Daniel Dunbarcf427c22011-11-03 17:55:59 +0000[diff] [blame]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>