diff --git a/llvm/docs/LLVMBuild.html b/llvm/docs/LLVMBuild.html new file mode 100644 index 000000000000..904d0e56e414 --- /dev/null +++ b/llvm/docs/LLVMBuild.html @@ -0,0 +1,328 @@ + + + + + LLVMBuild Documentation + + + + +

LLVMBuild Guide

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

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).

+
+ + +

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 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
+
+
+ +

LLVMBuild files are expected to define a strict set of section 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 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 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$ +
+ + diff --git a/llvm/docs/index.html b/llvm/docs/index.html index 4d74c549c71a..bfca45ba0a27 100644 --- a/llvm/docs/index.html +++ b/llvm/docs/index.html @@ -226,6 +226,10 @@ templates (directory organization, Makefiles, and test tree) allow the project code to be located outside (or inside) the llvm/ tree, while using LLVM header files and libraries. +
  • LLVMBuild Documentation - Describes the +LLVMBuild organization and files used by LLVM to specify component +descriptions.
    • +
  • LLVM Makefile Guide - Describes how the LLVM makefiles work and how to use them.