docs/Projects.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3         <head>
   4                 <title>Creating an LLVM Project</title>
   5         </head>
   6
   7         <body bgcolor=white>
   8
   9         <center><h1>Creating an LLVM Project<br></h1></center>
  10
  11         <!--===============================================================-->
  12         <h2><a name="a">Overview</a><hr></h2>
  13         <!--===============================================================-->
  14
  15         In order to set up a new project that uses the LLVM build system,
  16         libraries, and header files, follow these steps:
  17
  18         <ol>
  19                 <li>
  20                 Copy the <tt>llvm/projects/sample</tt> directory to any place
  21                 of your choosing.  You can place it anywhere you like, although
  22                 someplace underneath your home directory would work best.
  23                 <p>
  24
  25                 <li>
  26                 Edit the <tt>Makefile.config</tt> and <tt>Makefile.common</tt>
  27                 files so that the LLVM_SRC_ROOT variable equals the absolute
  28                 pathname of the LLVM source tree and LLVM_OBJ_ROOT equals the
  29                 pathname of where LLVM was built.
  30
  31                 <p>
  32
  33                 For example, if the LLVM source tree is in
  34                 <tt>/usr/home/joe/src/llvm</tt>, and you configured it with
  35                 <tt>--with-objroot=/tmp</tt> when his home directory is
  36                 <tt>/usr/home/joe</tt>, then
  37                 LLVM_SRC_ROOT=<tt>/usr/home/joe/src/llvm</tt> and
  38                 LLVM_OBJ_ROOT=<tt>/tmp/src/llvm</tt>.
  39                 <p>
  40
  41                 <li>
  42                 Add your source code to the source tree.
  43                 <p>
  44
  45                 <li>
  46                 Modify the various Makefiles to contain the names of the
  47                 objects that you want to build.
  48         </ol>
  49
  50         <!--===============================================================-->
  51         <h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
  52         <!--===============================================================-->
  53
  54         In order to use the LLVM build system, you will want to lay out your
  55         source code so that it can benefit from the build system's features.
  56         Mainly, you want your source tree layout to look similar to the LLVM
  57         source tree layout.  The best way to do this is to just copy the
  58         project tree from <tt>llvm/projects/sample</tt> and modify it to meet
  59         your needs, but you can certainly add to it if you want.
  60
  61         Underneath your top level directory, you should have the following
  62         directories:
  63
  64         <dl compact>
  65                 <dt><b>lib</b>
  66                 <dd>
  67                 This subdirectory should contain all of your library source
  68                 code.  For each library that you build, you will have one
  69                 directory in <b>lib</b> that will contain that library's source
  70                 code.
  71
  72                 <p>
  73                 Libraries can be object files, archives, or dynamic libraries.
  74                 The <b>lib</b> directory is just a good place for these as it
  75                 places them all in a directory from which they can be linked
  76                 later on.
  77
  78                 <dt><b>include</b>
  79                 <dd>
  80                 This subdirectory should contain any header files that are
  81                 global to your project.  By global, we mean that they are used
  82                 by more than one library or executable of your project.
  83                 <p>
  84                 By placing your header files in <b>include</b>, they will be
  85                 found automatically by the LLVM build system.  For example, if
  86                 you have a file <b>include/jazz/note.h</b>, then your source
  87                 files can include it simply with <b>#include "jazz/note.h"</b>.
  88
  89                 <dt><b>tools</b>
  90                 <dd>
  91                 This subdirectory should contain all of your source
  92                 code for executables.  For each program that you build, you
  93                 will have one directory in <b>tools</b> that will contain that
  94                 program's source code.
  95         </dl>
  96
  97         Typically, you will want to build your <b>lib</b> directory first
  98         followed by your <b>tools</b> directory.
  99
 100         <!--===============================================================-->
 101         <h2><a name="Makefile Variables">Makefile Variables</a><hr></h2>
 102         <!--===============================================================-->
 103         The LLVM build system provides several variables which you may
 104         use.
 105
 106         <h3> Required Variables </h3>
 107         <dl compact>
 108                 <dt>LEVEL
 109                 <dd>
 110                 This variable is the relative path from this Makefile to the
 111                 top directory of your project's source code.  For example, if
 112                 your source code is in /tmp/src, then the Makefile in
 113                 /tmp/src/jump/high would set LEVEL to "../..".
 114         </dl>
 115
 116         <h3> Variables for Building Subdirectories</h3>
 117         <dl compact>
 118                 <dt>DIRS
 119                 <dd>
 120                 This is a space separated list of subdirectories that should be
 121                 built.  They will be built, one at a time, in the order
 122                 specified.
 123                 <p>
 124
 125                 <dt>PARALLEL_DIRS
 126                 <dd>
 127                 This is a list of directories that can be built in parallel.
 128                 These will be built after the directories in DIRS have been
 129                 built.
 130                 <p>
 131
 132                 <dt>OPTIONAL_DIRS
 133                 <dd>
 134                 This is a list of directories that can be built if they exist,
 135                 but will not cause an error if they do not exist.  They are
 136                 built serially in the order in which they are listed.
 137         </dl>
 138
 139         <h3> Variables for Building Libraries</h3>
 140         <dl compact>
 141                 <dt>LIBRARYNAME
 142                 <dd>
 143                 This variable contains the base name of the library that will
 144                 be built.  For example, to build a library named
 145                 <tt>libsample.a</tt>, LIBRARYNAME should be set to
 146                 <tt>sample</tt>.
 147                 <p>
 148
 149                 <dt>BUILD_ARCHIVE
 150                 <dd>
 151                 By default, a library is a <tt>.o</tt> file that is linked
 152                 directly into a program.  However, if you set the BUILD_ARCHIVE
 153                 variable, an archive library (sometimes known as a static
 154                 library) will be built instead.
 155                 <p>
 156
 157                 <dt>SHARED_LIBRARY
 158                 <dd>
 159                 If SHARED_LIBRARY is defined in your Makefile, then the
 160                 Makefiles will generate a shared (or dynamic) library.
 161         </dl>
 162
 163         <h3> Variables for Building Programs</h3>
 164         <dl compact>
 165                 <dt>TOOLNAME
 166                 <dd>
 167                 This variable contains the name of the program that will
 168                 be built.  For example, to build an executable named
 169                 <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
 170                 <p>
 171
 172                 <dt>USEDLIBS
 173                 <dd>
 174                 This variable holds a space separated list of libraries that
 175                 should be linked into the program.  These libraries must either
 176                 be LLVM libraries or libraries that come from your <b>lib</b>
 177                 directory.  The libraries must be specified by their base name.
 178                 For example, to link libsample.a, you would set USEDLIBS to
 179                 <tt>sample</tt>.
 180                 <p>
 181         </dl>
 182
 183         <h3> Miscellaneous Variables</h3>
 184         <dl compact>
 185                 <dt>ExtraSource
 186                 <dd>
 187                 This variable contains a space separated list of extra source
 188                 files that needs to be built.  It is useful for including the
 189                 output of Lex and Yacc programs.
 190                 <p>
 191
 192                 <dt>CFLAGS
 193                 <dt>CPPFLAGS
 194                 <dd>
 195                 This variable can be used to add options to the C and C++
 196                 compiler, respectively.  It is typically used to add options
 197                 that tell the compiler the location of additional directories
 198                 to search for header files.
 199                 <p>
 200                 It is highly suggested that you append to these variable as
 201                 opposed to overwriting them.  The master Makefiles may already
 202                 have useful options in them that you may not want to overwrite.
 203                 <p>
 204         </dl>
 205
 206         <!--===============================================================-->
 207         <h2><a name="Caveats">Caveats</a><hr></h2>
 208         <!--===============================================================-->
 209
 210         Some caveats and known issues:
 211         <ol>
 212                 <li>
 213                 The projects system currently uses the $HOME environment
 214                 variable in determining where object files should go.  If $HOME
 215                 is not set, then your path relative to the root directory may
 216                 be used to determine where your object files go.  It is
 217                 therefore advised that your source directory reside underneath
 218                 your home directory.
 219         </ol>
 220 </body>
 221 </html>