From f6a0407ee5b89e8aabf93d818f98484764433115 Mon Sep 17 00:00:00 2001 From: Misha Brukman Date: Wed, 12 May 2004 20:57:43 +0000 Subject: Make file use stylesheets and be HTML-4.01 (Strict)-compliant. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@13506 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/Projects.html | 828 ++++++++++++++++++++++++++++------------------------- 1 file changed, 442 insertions(+), 386 deletions(-) (limited to 'docs/Projects.html') diff --git a/docs/Projects.html b/docs/Projects.html index a6527b0402..6be0a892f5 100644 --- a/docs/Projects.html +++ b/docs/Projects.html @@ -1,391 +1,447 @@ - + - - Creating an LLVM Project - - - - -

Creating an LLVM Project

- - -

Overview

- - - The LLVM build system is designed to facilitate the building of third party - projects that use LLVM header files, libraries, and tools. In order to use - these facilities, a Makefile from a project must do the following things: - -

Set environment variables. -
- There are several environment variables that a Makefile needs to set to - use the LLVM build system: -
-
LLVM_SRC_ROOT -
- The root of the LLVM source tree. -
- -
LLVM_OBJ_ROOT -
- The root of the LLVM object tree. -
- -
BUILD_SRC_ROOT -
- The root of the project's source tree. -
- -
BUILD_OBJ_ROOT -
- The root of the project's object tree. -
- -
BUILD_SRC_DIR -
- The directory containing the current source to be compiled. -
- -
BUILD_OBJ_DIR -
- The directory where the current source will place the new object - files. This should always be the current directory. -
- -
LEVEL -
- The relative path from the current directory to the root of the - object tree. -
-
- -
Include the LLVM Makefile.config from $(LLVM_OBJ_ROOT). -
- -
Include the LLVM Makefile.rules from $(LLVM_SRC_ROOT). -

- - There are two ways that you can set all of these variables: -

- You can write your own Makefiles which hard-code these values. - -
- You can use the pre-made LLVM sample project. This sample project - includes Makefiles, a configure script that can be used to configure - the location of LLVM, and the ability to support multiple object - directories from a single source directory. -

- - This document assumes that you will base your project off of the LLVM - sample project found in llvm/projects/sample. If you want to - devise your own build system, studying the sample project and LLVM - Makefiles will probably provide enough information on how to write your own - Makefiles. -

- - -

Create a Project from the Sample Project

- - - Follow these simple steps to start your project: - -

- Copy the llvm/projects/sample directory to any place - of your choosing. You can place it anywhere you like. Rename the - directory to match the name of your project. -
- -
- Add your source code and Makefiles to your source tree. -
- -
- If you want your Makefiles to be configured by the - configure script, or if you want to support multiple - object directories, add your Makefiles to the configure - script by adding them into the autoconf/configure.ac file. - The macro AC_CONFIG_MAKEFILE will copy a file, unmodified, - from the source directory to the object directory. - -
- After updating autoconf/configure.ac, regenerate the - configure script with these commands: -
- - cd autoconf - autoconf -o ../configure - - -
- - You must be using Autoconf version 2.57 or higher. -
- -
- Run configure in the directory in which you want to place - object code. Use the following options to tell your project where it - can find LLVM: - -
-
--with-llvmsrc=<directory> -
- Tell your project where the LLVM source tree is located. -
-
--with-llvmobj=<directory> -
- Tell your project where the LLVM object tree is located. -
-

- - That's it! Now all you have to do is type gmake in the root of - your object directory, and your project should build. - - -

Source Tree Layout

- - - In order to use the LLVM build system, you will want to organize your - source code so that it can benefit from the build system's features. - Mainly, you want your source tree layout to look similar to the LLVM - source tree layout. The best way to do this is to just copy the - project tree from llvm/projects/sample and modify it to meet - your needs, but you can certainly add to it if you want. - - Underneath your top level directory, you should have the following - directories: - -

lib -

- This subdirectory should contain all of your library source - code. For each library that you build, you will have one - directory in lib that will contain that library's source - code. - -

- Libraries can be object files, archives, or dynamic libraries. - The lib directory is just a convenient place for libraries - as it places them all in a directory from which they can be linked - later. - -

include -

- This subdirectory should contain any header files that are - global to your project. By global, we mean that they are used - by more than one library or executable of your project. -

- By placing your header files in include, they will be - found automatically by the LLVM build system. For example, if - you have a file include/jazz/note.h, then your source - files can include it simply with #include "jazz/note.h". - -

tools -

- This subdirectory should contain all of your source - code for executables. For each program that you build, you - will have one directory in tools that will contain that - program's source code. -

- -

test -

- This subdirectory should contain tests that verify that your code - works correctly. Automated tests are especially useful. -

- Currently, the LLVM build system provides little support for tests, - although some exists. Expanded support for tests will hopefully - occur in the future. In the meantime, the LLVM system does provide the - following: -

- LLVM provides several QMTest test classes that can be used to - create tests. They can be found in - llvm/test/QMTest/llvm.py. These test classes perform a - variety of functions, including code optimization tests, assembly - tests, and code analysis tests. The Makefile in - llvm/test provides the QMTest context needed by LLVM test - classes. -
- -
- The LLVM source tree provides benchmarks and programs which are - known to compile with the LLVM GCC front ends. You can use these - programs to test your code, gather statistics information, and - compare it to the current LLVM performance statistics. These - programs are found in the llvm/test/Programs directory. -
- Currently, there is no way to hook your tests directly into the - llvm/test/Programs testing harness. You will simply - need to find a way to use the source provided within that directory - on your own. -

- - Typically, you will want to build your lib directory first - followed by your tools directory. - - -

Writing LLVM Style Makefiles

- - The LLVM build system provides a convenient way to build libraries and - executables. Most of your project Makefiles will only need to define a few - variables. Below is a list of the variables one can set and what they can - do: - -

Required Variables

LEVEL -: - This variable is the relative path from this Makefile to the - top directory of your project's source code. For example, if - your source code is in /tmp/src, then the Makefile in - /tmp/src/jump/high would set LEVEL to "../..". -

- -

Variables for Building Subdirectories

DIRS -: - This is a space separated list of subdirectories that should be - built. They will be built, one at a time, in the order - specified. -
- -
PARALLEL_DIRS -: - This is a list of directories that can be built in parallel. - These will be built after the directories in DIRS have been - built. -
- -
OPTIONAL_DIRS -: - This is a list of directories that can be built if they exist, - but will not cause an error if they do not exist. They are - built serially in the order in which they are listed. -

- -

Variables for Building Libraries

LIBRARYNAME -: - This variable contains the base name of the library that will - be built. For example, to build a library named - libsample.a, LIBRARYNAME should be set to - sample. -
- -
BUILD_ARCHIVE -: - By default, a library is a .o file that is linked - directly into a program. To build an archive (also known as - a static library), set the BUILD_ARCHIVE variable. -
- -
SHARED_LIBRARY -: - If SHARED_LIBRARY is defined in your Makefile, a shared - (or dynamic) library will be built. -

- -

Variables for Building Programs

TOOLNAME -

- This variable contains the name of the program that will - be built. For example, to build an executable named - sample, TOOLNAME should be set to sample. -

- -

USEDLIBS -

- This variable holds a space separated list of libraries that - should be linked into the program. These libraries must either - be LLVM libraries or libraries that come from your lib - directory. The libraries must be specified by their base name. - For example, to link libsample.a, you would set USEDLIBS to - sample. -

- Note that this works only for statically linked libraries. -

- -

LIBS -

- To link dynamic libraries, add -l<library base name> to - the LIBS variable. The LLVM build system will look in the same places - for dynamic libraries as it does for static libraries. -

- For example, to link libsample.so, you would have the - following line in your Makefile: -

- - LIBS+=-lsample - -

- -

Miscellaneous Variables

ExtraSource -

- This variable contains a space separated list of extra source - files that need to be built. It is useful for including the - output of Lex and Yacc programs. -

- -

CFLAGS -

CPPFLAGS -

- This variable can be used to add options to the C and C++ - compiler, respectively. It is typically used to add options - that tell the compiler the location of additional directories - to search for header files. -

- It is highly suggested that you append to CFLAGS and CPPFLAGS as - opposed to overwriting them. The master Makefiles may already - have useful options in them that you may not want to overwrite. -

- - -

Placement of Object Code

- - - The final location of built libraries and executables will depend upon - whether you do a Debug, Release, or Profile build. - -

Libraries -: - All libraries (static and dynamic) will be stored in - BUILD_OBJ_ROOT/lib/<type>, where type is Debug, - Release, or Profile for a debug, optimized, or - profiled build, respectively. -
- -
Executables -: - All executables will be stored in BUILD_OBJ_ROOT/lib/<type>, - where type is Debug, Release, or Profile for - a debug, optimized, or profiled build, respectively. -

- - -

Further Help

- - - If you have any questions or need any help creating an LLVM project, - the LLVM team would be more than happy to help. You can always post your - questions to the LLVM Developers - Mailing List. - + + Creating an LLVM Project + + + + +

Creating an LLVM Project

+ +

Overview
Create a project from the Sample Project
Source tree layout
Writing LLVM-style Makefiles +
Placement of object code
Further help

+ + +

Overview

+ + +

+ +

The LLVM build system is designed to facilitate the building of third party +projects that use LLVM header files, libraries, and tools. In order to use +these facilities, a Makefile from a project must do the following things:

+ +

Set environment variables.There are several environment variables that a +Makefile needs to set to use the LLVM build system: + +
- LLVM_SRC_ROOT - The root of the LLVM source tree.
- LLVM_OBJ_ROOT - The root of the LLVM object tree.
- BUILD_SRC_ROOT - The root of the project's source tree.
- BUILD_OBJ_ROOT - The root of the project's object tree.
- BUILD_SRC_DIR - The directory containing the current source to be + compiled.
- BUILD_OBJ_DIR - The directory where the current source will place + the new object files. This should always be the current directory.
- LEVEL - The relative path from the current directory to the root + of the object tree.
Include Makefile.config from $(LLVM_OBJ_ROOT).
Include Makefile.rules from $(LLVM_SRC_ROOT).

+ +

There are two ways that you can set all of these variables:

+ +

You can write your own Makefiles which hard-code these values.
You can use the pre-made LLVM sample project. This sample project includes +Makefiles, a configure script that can be used to configure the location of +LLVM, and the ability to support multiple object directories from a single +source directory.

+ +

This document assumes that you will base your project off of the LLVM sample +project found in llvm/projects/sample. If you want to devise your own +build system, studying the sample project and LLVM Makefiles will probably +provide enough information on how to write your own Makefiles.

+ +

+ + +

+ Create a Project from the Sample Project +

+ + +

+ +

Follow these simple steps to start your project:

+ +

Copy the llvm/projects/sample directory to any place of your +choosing. You can place it anywhere you like. Rename the directory to match +the name of your project.
Add your source code and Makefiles to your source tree.
If you want your Makefiles to be configured by the configure +script, or if you want to support multiple object directories, add your +Makefiles to the configure script by adding them into the +autoconf/configure.ac file. The macro AC_CONFIG_MAKEFILE will +copy a file, unmodified, from the source directory to the object directory.
After updating autoconf/configure.ac, regenerate the +configure script with these commands: + +
+
% cd autoconf + % autoconf -o ../configure
+
+ +
You must be using Autoconf version 2.57 or higher.
Run configure in the directory in which you want to place +object code. Use the following options to tell your project where it +can find LLVM: + +
+
--with-llvmsrc=<directory> +
+ Tell your project where the LLVM source tree is located. +
+
--with-llvmobj=<directory> +
+ Tell your project where the LLVM object tree is located. +
+

+ +

That's it! Now all you have to do is type gmake in the root of +your object directory, and your project should build.

+ +

+ + +

+ Source Tree Layout +

+ + +

+ +

In order to use the LLVM build system, you will want to organize your +source code so that it can benefit from the build system's features. +Mainly, you want your source tree layout to look similar to the LLVM +source tree layout. The best way to do this is to just copy the +project tree from llvm/projects/sample and modify it to meet +your needs, but you can certainly add to it if you want.

+ +

Underneath your top level directory, you should have the following +directories:

+ +

lib +

+ This subdirectory should contain all of your library source + code. For each library that you build, you will have one + directory in lib that will contain that library's source + code. + +

+ Libraries can be object files, archives, or dynamic libraries. + The lib directory is just a convenient place for libraries + as it places them all in a directory from which they can be linked + later. + +

include +

+ This subdirectory should contain any header files that are + global to your project. By global, we mean that they are used + by more than one library or executable of your project. +

+ By placing your header files in include, they will be + found automatically by the LLVM build system. For example, if + you have a file include/jazz/note.h, then your source + files can include it simply with #include "jazz/note.h". + +

tools +

+ This subdirectory should contain all of your source + code for executables. For each program that you build, you + will have one directory in tools that will contain that + program's source code. +

+ +

test +

+ This subdirectory should contain tests that verify that your code + works correctly. Automated tests are especially useful. +

+ Currently, the LLVM build system provides little support for tests, + although some exists. Expanded support for tests will hopefully + occur in the future. In the meantime, the LLVM system does provide the + following: +

+ LLVM provides several QMTest test classes that can be used to + create tests. They can be found in + llvm/test/QMTest/llvm.py. These test classes perform a + variety of functions, including code optimization tests, assembly + tests, and code analysis tests. The Makefile in + llvm/test provides the QMTest context needed by LLVM test + classes. +
+ +
+ The LLVM source tree provides benchmarks and programs which are + known to compile with the LLVM GCC front ends. You can use these + programs to test your code, gather statistics information, and + compare it to the current LLVM performance statistics. These + programs are found in the llvm/test/Programs directory. +
+ Currently, there is no way to hook your tests directly into the + llvm/test/Programs testing harness. You will simply + need to find a way to use the source provided within that directory + on your own. +

+ +

Typically, you will want to build your lib directory first followed by +your tools directory.

+ +

+ + +

+ Writing LLVM Style Makefiles +

+ + +

+ +

The LLVM build system provides a convenient way to build libraries and +executables. Most of your project Makefiles will only need to define a few +variables. Below is a list of the variables one can set and what they can +do:

+ +

+ + +

+ Required Variables +

+ +

LEVEL +: + This variable is the relative path from this Makefile to the + top directory of your project's source code. For example, if + your source code is in /tmp/src, then the Makefile in + /tmp/src/jump/high would set LEVEL to "../..". +

+ +

+ + +

+ Variables for Building Subdirectories +

+ +

DIRS +: + This is a space separated list of subdirectories that should be + built. They will be built, one at a time, in the order + specified. +
+ +
PARALLEL_DIRS +: + This is a list of directories that can be built in parallel. + These will be built after the directories in DIRS have been + built. +
+ +
OPTIONAL_DIRS +: + This is a list of directories that can be built if they exist, + but will not cause an error if they do not exist. They are + built serially in the order in which they are listed. +

+ +

+ + +

+ Variables for Building Libraries +

+ +

LIBRARYNAME +: + This variable contains the base name of the library that will + be built. For example, to build a library named + libsample.a, LIBRARYNAME should be set to + sample. +
+ +
BUILD_ARCHIVE +: + By default, a library is a .o file that is linked + directly into a program. To build an archive (also known as + a static library), set the BUILD_ARCHIVE variable. +
+ +
SHARED_LIBRARY +: + If SHARED_LIBRARY is defined in your Makefile, a shared + (or dynamic) library will be built. +

+ +

+ + +

+ Variables for Building Programs +

+ +

TOOLNAME +

+ This variable contains the name of the program that will + be built. For example, to build an executable named + sample, TOOLNAME should be set to sample. +

+ +

USEDLIBS +

+ This variable holds a space separated list of libraries that + should be linked into the program. These libraries must either + be LLVM libraries or libraries that come from your lib + directory. The libraries must be specified by their base name. + For example, to link libsample.a, you would set USEDLIBS to + sample. +

+ Note that this works only for statically linked libraries. +

+ +

LIBS +

+ To link dynamic libraries, add -l<library base name> to + the LIBS variable. The LLVM build system will look in the same places + for dynamic libraries as it does for static libraries. +

+ For example, to link libsample.so, you would have the + following line in your Makefile: +

+ + LIBS += -lsample + +

+ +

+ + +

+ Miscellaneous Variables +

+ +

ExtraSource +

+ This variable contains a space separated list of extra source + files that need to be built. It is useful for including the + output of Lex and Yacc programs. +

+ +

CFLAGS +

CPPFLAGS +

+ This variable can be used to add options to the C and C++ + compiler, respectively. It is typically used to add options + that tell the compiler the location of additional directories + to search for header files. +

+ It is highly suggested that you append to CFLAGS and CPPFLAGS as + opposed to overwriting them. The master Makefiles may already + have useful options in them that you may not want to overwrite. +

+ +

+ + +

+ Placement of Object Code +

+ + +

+ +

The final location of built libraries and executables will depend upon +whether you do a Debug, Release, or Profile build.

+ +

Libraries +: + All libraries (static and dynamic) will be stored in + BUILD_OBJ_ROOT/lib/<type>, where type is Debug, + Release, or Profile for a debug, optimized, or + profiled build, respectively.
+ +
Executables +: All executables will be stored in + BUILD_OBJ_ROOT/tools/<type>, where type is Debug, + Release, or Profile for a debug, optimized, or profiled + build, respectively. +

+ +

+ + +

+ Further Help +

+ + +

+ +

If you have any questions or need any help creating an LLVM project, +the LLVM team would be more than happy to help. You can always post your +questions to the LLVM Developers +Mailing List.

+ +

John Criswell

-The LLVM Compiler Infrastructure
-Last modified: $Date$ +

+ + John Criswell
+ The LLVM Compiler Infrastructure +
+ Last modified: $Date$ +

-- cgit v1.2.3