X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FProjects.html;h=ada6196be2a9f3f214002015288b3768ff175286;hb=38d49ad08326b3bf959b674dbf6be065b0b9366f;hp=b3b22b6738049836cd5e02fcd7b2e29a562a66cc;hpb=c7b6ce4af8e2c16e2f4287eedea25c426ac844a2;p=oota-llvm.git diff --git a/docs/Projects.html b/docs/Projects.html index b3b22b67380..ada6196be2a 100644 --- a/docs/Projects.html +++ b/docs/Projects.html @@ -1,206 +1,460 @@ - + - - Creating an LLVM Project - - - - -

Creating an LLVM Project

- - -

Overview

- - - In order to set up a new project that uses the LLVM build system, - libraries, and header files, follow these steps: - -
    -
  1. - Copy the llvm/projects/sample directory to any place - of your choosing. You can place it anywhere you like, although - someplace underneath your home directory would work best. -

    - -

  2. - Edit the Makefile.config and Makefile.common - files so that the LLVM_SRC_ROOT variable equals the absolute - pathname of the LLVM source tree and LLVM_OBJ_ROOT equals the - pathname of where LLVM was built. - -

    - - For example, if the LLVM source tree is in - /usr/home/joe/src/llvm, and you built LLVM in - /tmp/llvmobj, then - LLVM_SRC_ROOT=/usr/home/joe/src/llvm and - LLVM_OBJ_ROOT=/tmp/llvmobj. -

    - -

  3. - Add your source code to your source tree. -

    - -

  4. - Modify the various Makefiles to contain the names of the - objects that you want to build. -
- - -

Source Tree Layout

- - - In order to use the LLVM build system, you will want to lay out 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 good place for these 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. -
- - Typically, you will want to build your lib directory first - followed by your tools directory. - - -

Makefile Variables

- - The LLVM build system provides several variables which you may - use. - -

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. However, if you set the BUILD_ARCHIVE - variable, an archive library (sometimes known as a static - library) will be built instead. -

- -

SHARED_LIBRARY -
- If SHARED_LIBRARY is defined in your Makefile, then the - Makefiles will generate a shared (or dynamic) library. -
- -

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

-

- -

Miscellaneous Variables

-
-
ExtraSource -
- This variable contains a space separated list of extra source - files that needs 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 these variable as - opposed to overwriting them. The master Makefiles may already - have useful options in them that you may not want to overwrite. -

-

+ + Creating an LLVM Project + + + + +
Creating an LLVM Project
+ +
    +
  1. Overview
    2. +
  2. Create a project from the Sample Project
    3. +
  3. Source tree layout
    4. +
  4. Writing LLVM-style Makefiles +
      +
    1. Required Variables
      2. +
    2. Variables for Building Subdirectories
      3. +
    3. Variables for Building Libraries
      4. +
    4. Variables for Building Programs
      5. +
    5. Miscellaneous Variables
      6. +
    5. +
  5. Placement of object code
    6. +
  6. Further help
    7. +
+ +
+

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:

+ +
    +
  1. 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).
      • +
    2. +
  2. Include Makefile.config from $(LLVM_OBJ_ROOT).
    3. +
  3. Include Makefile.rules from $(LLVM_SRC_ROOT).
    4. +
+ +

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

+
    +
  1. You can write your own Makefiles which hard-code these values.
    2. +
  2. 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.
    3. +
+ +

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:

+ +
    +
  1. 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.
    2. + +
  2. +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.
    3. + +
  3. Add your source code and Makefiles to your source tree.
    4. + +
  4. 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.
      • +
    +
    5. + +
  5. 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.

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

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