LLVMBuild Guide

  1. Introduction
  2. Project Organization
  3. Build Integration
  4. Component Overview
  5. Format Reference

Introduction

This document describes the LLVMBuild organization and files which we use to describe parts of the LLVM ecosystem. For description of specific LLVMBuild related tools, please see the command guide.

LLVM is designed to be a modular set of libraries which can be flexibly mixed together in order to build a variety of tools, like compilers, JITs, custom code generators, optimization passes, interpreters, and so on. Related projects in the LLVM system like Clang and LLDB also tend to follow this philosophy.

In order to support this usage style, LLVM has a fairly strict structure as to how the source code and various components are organized. The LLVMBuild.txt files are the explicit specification of that structure, and are used by the build systems and other tools in order to develop the LLVM project.

Project Organization

The source code for LLVM projects using the LLVMBuild system (LLVM, Clang, and LLDB) is organized into components, which define the separate pieces of functionality that make up the project. These projects may consist of many libraries, associated tools, build tools, or other utility tools (for example, testing tools).

For the most part, the project contents are organized around defining one main component per each subdirectory. Each such directory contains an LLVMBuild.txt which contains the component definitions.

The component descriptions for the project as a whole are automatically gathered by the LLVMBuild tools. The tools automatically traverse the source directory structure to find all of the component description files. NOTE: For performance/sanity reasons, we only traverse into subdirectories when the parent itself contains an LLVMBuild.txt description file.

Build Integration

The LLVMBuild files themselves are just a declarative way to describe the project structure. The actual building of the LLVM project is handled by another build system (currently we support both Makefiles and CMake.

The build system implementation will load the relevant contents of the LLVMBuild files and use that to drive the actual project build. Typically, the build system will only need to load this information at "configure" time, and use it to generative native information. Build systems will also handle automatically reconfiguring their information when the contents of the LLVMBuild.txt files change.

Developers generally are not expected to need to be aware of the details of how the LLVMBuild system is integrated into their build. Ideally, LLVM developers who are not working on the build system would only ever need to modify the contents of the LLVMBuild.txt description files (although we have not reached this goal yet).

For more information on the utility tool we provide to help interfacing with the build system, please see the llvm-build documentation.

Component Overview

As mentioned earlier, LLVM projects are organized into logical components. Every component is typically grouped into it's own subdirectory. Generally, a component is organized around a coherent group of sources which have some kind of clear API separation from other parts of the code.

LLVM primarily uses the following types of components:

Components are described using LLVMBuild.txt files in the directories that define the component. See the Format Reference section for information on the exact format of these files.

LLVMBuild Format Reference

LLVMBuild files are written in a simple variant of the INI or configuration file format (Wikipedia entry). The format defines a list of sections each of which may contain some number of properties. A simple example of the file format is below:

; Comments start with a semi-colon.

; Sections are declared using square brackets.
[component_0]

; Properties are declared using '=' and are contained in the previous section.
;
; We support simple string and boolean scalar values and list values, where
; items are separated by spaces. There is no support for quoting, and so
; property values may not contain spaces.
property_name = property_value
list_property_name = value_1 value_2 ... value_n
boolean_property_name = 1 (or 0)

LLVMBuild files are expected to define a strict set of sections and properties. An typical component description file for a library component would look typically look like the following example:

[component_0]
type = Library
name = Linker
parent = Libraries
required_libraries = Archive BitReader Core Support TransformUtils

A full description of the exact sections and properties which are allowed follows.

Each file may define exactly one common component, named "common". The common component may define the following properties:

Each file may define multiple components. Each component is described by a section who name starts with "component". The remainder of the section name is ignored, but each section name must be unique. Typically components are just number in order for files with multiple components ("component_0", "component_1", and so on).

Section names not matches this format (or the "common" section) are currently unused and are disallowed.

Every component is defined by the properties in the section. The exact list of properties that are allowed depends on the component type. Components may not define any properties other than those expected by the component type.

Every component must define the following properties:

Components may define the following properties:

The following section lists the available component types, as well as the properties which are associated with that component.

Valid CSS Valid HTML 4.01 The LLVM Compiler Infrastructure
Last modified: $Date$