Date: Wed, 15 Aug 2012 19:34:23 +0000 Subject: Vendor import of llvm trunk r161861: http://llvm.org/svn/llvm-project/llvm/trunk@161861 --- docs/Projects.html | 489 ----------------------------------------------------- 1 file changed, 489 deletions(-) delete mode 100644 docs/Projects.html (limited to 'docs/Projects.html') diff --git a/docs/Projects.html b/docs/Projects.html deleted file mode 100644 index ebd7203..0000000 --- a/docs/Projects.html +++ /dev/null @@ -1,489 +0,0 @@ - - - - - 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

- -

Written by John Criswell

- - -

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 make variables. There are several variables that a Makefile - needs to set to use the LLVM build system: -
- PROJECT_NAME - The name by which your project is known.
- LLVM_SRC_ROOT - The root of the LLVM source tree.
- LLVM_OBJ_ROOT - The root of the LLVM object tree.
- PROJ_SRC_ROOT - The root of the project's source tree.
- PROJ_OBJ_ROOT - The root of the project's object tree.
- PROJ_INSTALL_ROOT - The root installation directory.
- LEVEL - The relative path from the current directory to the - project's root ($PROJ_OBJ_ROOT).
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 on 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.
-If you downloaded LLVM using Subversion, remove all the directories named .svn -(and all the files therein) from your project's new source tree. This will -keep Subversion from thinking that your project is inside -llvm/trunk/projects/sample.
Add your source code and Makefiles to your source tree.
If you want your project to be configured with the configure script -then you need to edit autoconf/configure.ac as follows: -
- AC_INIT. Place the name of your project, its version number and - a contact email address for your project as the arguments to this macro
- AC_CONFIG_AUX_DIR. If your project isn't in the - llvm/projects directory then you might need to adjust this so that - it specifies a relative path to the llvm/autoconf directory.
- LLVM_CONFIG_PROJECT. Just leave this alone.
- AC_CONFIG_SRCDIR. Specify a path to a file name that identifies - your project; or just leave it at Makefile.common.in
- AC_CONFIG_FILES. Do not change.
- AC_CONFIG_MAKEFILE. Use one of these macros for each Makefile - that your project uses. This macro arranges for your makefiles to be copied - from the source directory, unmodified, to the build directory.
-
After updating autoconf/configure.ac, regenerate the -configure script with these commands: - -
-
% cd autoconf - % ./AutoRegen.sh
-
- -
You must be using Autoconf version 2.59 or later and your aclocal version -should be 1.9 or later.
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.
-

--prefix=<directory>
-
Tell your project where it should get installed.
-
-

- -

That's it! Now all you have to do is type gmake (or make -if your on a GNU/Linux system) 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 basic support for tests. - The LLVM system provides the following: -

- LLVM provides a tcl procedure that is used by Dejagnu to run - tests. It can be found in llvm/lib/llvm-dg.exp. This - test procedure uses RUN lines in the actual test case to determine - how to run the test. See the TestingGuide for more details. You - can easily write Makefile support similar to the Makefiles in - llvm/test to use Dejagnu to run your project's tests.
- LLVM contains an optional package called llvm-test - which provides benchmarks and programs that 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. -
Currently, there is no way to hook your tests directly into the - llvm/test 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 be libraries that - come from your lib directory. The libraries must be - specified without their "lib" prefix. For example, to link - libsample.a, you would set USEDLIBS to - sample.a. -

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

- -

LLVMLIBS -

- This variable holds a space separated list of libraries that should - be linked into the program. These libraries must be LLVM libraries. - The libraries must be specified without their "lib" prefix. For - example, to link with a driver that performs an IR transformation - you might set LLVMLIBS to this minimal set of libraries - LLVMSupport.a LLVMCore.a LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a LLVMScalarOpts.a LLVMTarget.a. -

- Note that this works only for statically linked libraries. LLVM is - split into a large number of static libraries, and the list of libraries you - require may be much longer than the list above. To see a full list - of libraries use: - llvm-config --libs all. - Using LINK_COMPONENTS as described below, obviates the need to set LLVMLIBS. -

- -

LINK_COMPONENTS -

This variable holds a space separated list of components that - the LLVM Makefiles pass to the llvm-config tool to generate - a link line for the program. For example, to link with all LLVM - libraries use - LINK_COMPONENTS = all. -

- -

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

- Note that LIBS must occur in the Makefile after the inclusion of Makefile.common. -

- -

- - -

- 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 - PROJ_OBJ_ROOT/<type>/lib, where type is Debug, - Release, or Profile for a debug, optimized, or - profiled build, respectively.
- -
Executables -: All executables will be stored in - PROJ_OBJ_ROOT/<type>/bin, 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: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ -

- - - -- cgit v1.1