[ARM] Selection for MVE VMOVN
[llvm-complete.git] / docs / LLVMBuild.rst
blob622780aee3124f806e30968119bf726363fdbfef
1 ===============
2 LLVMBuild Guide
3 ===============
5 .. contents::
6    :local:
8 Introduction
9 ============
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.
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.
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.
27 Project Organization
28 ====================
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).
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.
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.
47 Build Integration
48 =================
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 (See: :doc:`CMake <CMake>`).
54 The build system implementation will load the relevant contents of the
55 LLVMBuild files and use that to drive the actual project build.
56 Typically, the build system will only need to load this information at
57 "configure" time, and use it to generate native information. Build
58 systems will also handle automatically reconfiguring their information
59 when the contents of the ``LLVMBuild.txt`` files change.
61 Developers generally are not expected to need to be aware of the details
62 of how the LLVMBuild system is integrated into their build. Ideally,
63 LLVM developers who are not working on the build system would only ever
64 need to modify the contents of the ``LLVMBuild.txt`` description files
65 (although we have not reached this goal yet).
67 For more information on the utility tool we provide to help interfacing
68 with the build system, please see the :doc:`llvm-build
69 <CommandGuide/llvm-build>` documentation.
71 Component Overview
72 ==================
74 As mentioned earlier, LLVM projects are organized into logical
75 *components*. Every component is typically grouped into its own
76 subdirectory. Generally, a component is organized around a coherent
77 group of sources which have some kind of clear API separation from other
78 parts of the code.
80 LLVM primarily uses the following types of components:
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.
94 Components are described using ``LLVMBuild.txt`` files in the directories
95 that define the component. See the `LLVMBuild Format Reference`_ section
96 for information on the exact format of these files.
98 LLVMBuild Format Reference
99 ==========================
101 LLVMBuild files are written in a simple variant of the INI or configuration
102 file format (`Wikipedia entry`_). The format defines a list of sections
103 each of which may contain some number of properties. A simple example of
104 the file format is below:
106 .. _Wikipedia entry: http://en.wikipedia.org/wiki/INI_file
108 .. code-block:: ini
110    ; Comments start with a semi-colon.
112    ; Sections are declared using square brackets.
113    [component_0]
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)
124 LLVMBuild files are expected to define a strict set of sections and
125 properties. A typical component description file for a library
126 component would look like the following example:
128 .. code-block:: ini
130    [component_0]
131    type = Library
132    name = Linker
133    parent = Libraries
134    required_libraries = Archive BitReader Core Support TransformUtils
136 A full description of the exact sections and properties which are
137 allowed follows.
139 Each file may define exactly one common component, named ``common``. The
140 common component may define the following properties:
142 -  ``subdirectories`` **[optional]**
144    If given, a list of the names of the subdirectories from the current
145    subpath to search for additional LLVMBuild files.
147 Each file may define multiple components. Each component is described by a
148 section who name starts with ``component``. The remainder of the section
149 name is ignored, but each section name must be unique. Typically components
150 are just number in order for files with multiple components
151 (``component_0``, ``component_1``, and so on).
153 .. warning::
155    Section names not matching this format (or the ``common`` section) are
156    currently unused and are disallowed.
158 Every component is defined by the properties in the section. The exact
159 list of properties that are allowed depends on the component type.
160 Components **may not** define any properties other than those expected
161 by the component type.
163 Every component must define the following properties:
165 -  ``type`` **[required]**
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.
171 -  ``name`` **[required]**
173    The name of the component. Names are required to be unique across the
174    entire project.
176 -  ``parent`` **[required]**
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.
184    Components may reference the root pseudo component using ``$ROOT`` to
185    indicate they should logically be grouped at the top-level.
187 Components may define the following properties:
189 -  ``dependencies`` **[optional]**
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.
195    .. note::
197       ``Group`` and ``LibraryGroup`` components have no semantics for the
198       actual build, and are not allowed to specify dependencies.
200 The following section lists the available component types, as well as
201 the properties which are associated with that component.
203 -  ``type = Group``
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.
209    ``Group`` components have no additionally properties.
211 -  ``type = Library``
213    Library components define an individual library which should be built
214    from the source code in the component directory.
216    Components with this type use the following properties:
218    -  ``library_name`` **[optional]**
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.
223    -  ``required_libraries`` **[optional]**
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.
231    -  ``add_to_library_groups`` **[optional]**
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.
239    -  ``installed`` **[optional]** **[boolean]**
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.
245 -  ``type = LibraryGroup``
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".
251    Components with this type use the following properties:
253    -  ``required_libraries`` **[optional]**
255       See the ``Library`` type for a description of this property.
257    -  ``add_to_library_groups`` **[optional]**
259       See the ``Library`` type for a description of this property.
261 -  ``type = TargetGroup``
263    ``TargetGroup`` components are an extension of ``LibraryGroup``\s,
264    specifically for defining LLVM targets (which are handled specially in a
265    few places).
267    The name of the component should always be the name of the target.
269    Components with this type use the ``LibraryGroup`` properties in
270    addition to:
272    -  ``has_asmparser`` **[optional]** **[boolean]**
274       Whether this target defines an assembly parser.
276    -  ``has_asmprinter`` **[optional]** **[boolean]**
278       Whether this target defines an assembly printer.
280    -  ``has_disassembler`` **[optional]** **[boolean]**
282       Whether this target defines a disassembler.
284    -  ``has_jit`` **[optional]** **[boolean]**
286       Whether this target supports JIT compilation.
288 -  ``type = Tool``
290    ``Tool`` components define standalone command line tools which should be
291    built from the source code in the component directory and linked.
293    Components with this type use the following properties:
295    -  ``required_libraries`` **[optional]**
297       If given, a list of the names of ``Library`` or ``LibraryGroup``
298       components which this tool is required to be linked with.
300       .. note::
302          The values should be the component names, which may not always
303          match up with the actual library names on disk.
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``).
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``.
313 -  ``type = BuildTool``
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.
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.