diff --git a/docs/Projects.html b/docs/Projects.html index a6527b0402f..6be0a892f5b 100644 --- a/docs/Projects.html +++ b/docs/Projects.html @@ -1,391 +1,447 @@ - + - - Creating an LLVM Project - + + Creating an LLVM Project + + + - +
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. +
- -

Overview

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

    +

    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:

    -
    LLVM_OBJ_ROOT -
    - The root of the LLVM object tree. -

    +

      +
    1. Set environment variables.There are several environment variables that a +Makefile needs to set to use the LLVM build system: -
      BUILD_SRC_ROOT -
      - The root of the project's source tree. -

      +

        +
      • 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.
        • +
      2. +
    2. Include Makefile.config from $(LLVM_OBJ_ROOT).
      3. +
    3. Include Makefile.rules from $(LLVM_SRC_ROOT).
      4. +
    -
    BUILD_OBJ_ROOT -
    - The root of the project's object tree. -

    +

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

    -
    BUILD_SRC_DIR -
    - The directory containing the current source to be compiled. -

    +

      +
    1. You can write your own Makefiles which hard-code these values.
      2. -
      BUILD_OBJ_DIR -
      - The directory where the current source will place the new object - files. This should always be the current directory. -

      +

    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. +
    -
    LEVEL -
    - The relative path from the current directory to the root of the - object tree. -

    -

    +

    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.

    -
  2. Include the LLVM Makefile.config from $(LLVM_OBJ_ROOT). -

    +

-
  • Include the LLVM Makefile.rules from $(LLVM_SRC_ROOT). - + +
    + Create a Project from the Sample Project +
    + - 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. - 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. -
    +

    Follow these simple steps to start your project:

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

    +

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

      Create a Project from the Sample Project

      - +
    2. Add your source code and Makefiles to your source tree.
      3. - Follow these simple steps to start your project: +
    3. 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.
      4. -
        -
      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. After updating autoconf/configure.ac, regenerate the +configure script with these commands: -
      3. - Add your source code and Makefiles to your source tree. -

        +

        +

        % cd autoconf
        + % autoconf -o ../configure

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

        You must be using Autoconf version 2.57 or higher.

        5. -

        - After updating autoconf/configure.ac, regenerate the - configure script with these commands: -

        - - cd autoconf
        - autoconf -o ../configure -         +

      5. 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. +
        +
      - You must be using Autoconf version 2.57 or higher. -

      +

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

      -
    4. - 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. -
      -
    + +
    + Source Tree Layout +
    + - 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.

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

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

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

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

    -

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

      -

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

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

    - 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: + +
    + Writing LLVM Style Makefiles +
    + -

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

    +

    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:

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

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

    +

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

    + +

    + Variables for Building Subdirectories +
    -
    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 - -

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

    -

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

    +

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

    -

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

    -

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

    Placement of Object Code

    - + - The final location of built libraries and executables will depend upon - whether you do a Debug, Release, or Profile build. + +
    + Variables for Building Libraries +
    -
    -
    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. -
    +
    +
    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. +

    - -

    Further Help

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

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

    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$ +
    + Valid CSS! + Valid HTML 4.01! + + John Criswell
    + The LLVM Compiler Infrastructure +
    + Last modified: $Date$ +