diff --git a/docs/Projects.html b/docs/Projects.html new file mode 100644 index 00000000000..2debb6f7be1 --- /dev/null +++ b/docs/Projects.html @@ -0,0 +1,221 @@ + + + + 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 configured it with + --with-objroot=/tmp when his home directory is + /usr/home/joe, then + LLVM_SRC_ROOT=/usr/home/joe/src/llvm and + LLVM_OBJ_ROOT=/tmp/src/llvm. +

    + +

  3. + Add your source code to the 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 on. + +

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

+

+ + +

Caveats

+ + + Some caveats and known issues: +
    +
  1. + The projects system currently uses the $HOME environment + variable in determining where object files should go. If $HOME + is not set, then your path relative to the root directory may + be used to determine where your object files go. It is + therefore advised that your source directory reside underneath + your home directory. +
+ +