]>
Commit | Line | Data |
---|---|---|
970d7e83 LB |
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). | |
1a4d82fc JJ |
89 | Currently, LLVM uses one main build tool called :doc:`TableGen/index` |
90 | to generate a variety of source files. | |
970d7e83 LB |
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 | |
1a4d82fc JJ |
126 | properties. A typical component description file for a library |
127 | component would look like the following example: | |
970d7e83 LB |
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 | |
1a4d82fc | 318 | (instead of that platform being targeted). Build systems are expected |
970d7e83 LB |
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 |