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 built LLVM in
  35                 /tmp/llvmobj</tt>, then
  36                 LLVM_SRC_ROOT=<tt>/usr/home/joe/src/llvm</tt> and
  37                 LLVM_OBJ_ROOT=<tt>/tmp/llvmobj</tt>.
  38                 <p>
  39
  40                 <li>
  41                 Add your source code to your source tree.
  42                 <p>
  43
  44                 <li>
  45                 Modify the various Makefiles to contain the names of the
  46                 objects that you want to build.
  47         </ol>
  48
  49         <!--===============================================================-->
  50         <h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
  51         <!--===============================================================-->
  52
  53         In order to use the LLVM build system, you will want to lay out your
  54         source code so that it can benefit from the build system's features.
  55         Mainly, you want your source tree layout to look similar to the LLVM
  56         source tree layout.  The best way to do this is to just copy the
  57         project tree from <tt>llvm/projects/sample</tt> and modify it to meet
  58         your needs, but you can certainly add to it if you want.
  59
  60         Underneath your top level directory, you should have the following
  61         directories:
  62
  63         <dl compact>
  64                 <dt><b>lib</b>
  65                 <dd>
  66                 This subdirectory should contain all of your library source
  67                 code.  For each library that you build, you will have one
  68                 directory in <b>lib</b> that will contain that library's source
  69                 code.
  70
  71                 <p>
  72                 Libraries can be object files, archives, or dynamic libraries.
  73                 The <b>lib</b> directory is just a good place for these as it
  74                 places them all in a directory from which they can be linked
  75                 later.
  76
  77                 <dt><b>include</b>
  78                 <dd>
  79                 This subdirectory should contain any header files that are
  80                 global to your project.  By global, we mean that they are used
  81                 by more than one library or executable of your project.
  82                 <p>
  83                 By placing your header files in <b>include</b>, they will be
  84                 found automatically by the LLVM build system.  For example, if
  85                 you have a file <b>include/jazz/note.h</b>, then your source
  86                 files can include it simply with <b>#include "jazz/note.h"</b>.
  87
  88                 <dt><b>tools</b>
  89                 <dd>
  90                 This subdirectory should contain all of your source
  91                 code for executables.  For each program that you build, you
  92                 will have one directory in <b>tools</b> that will contain that
  93                 program's source code.
  94         </dl>
  95
  96         Typically, you will want to build your <b>lib</b> directory first
  97         followed by your <b>tools</b> directory.
  98
  99         <!--===============================================================-->
 100         <h2><a name="Makefile Variables">Makefile Variables</a><hr></h2>
 101         <!--===============================================================-->
 102         The LLVM build system provides several variables which you may
 103         use.
 104
 105         <h3> Required Variables </h3>
 106         <dl compact>
 107                 <dt>LEVEL
 108                 <dd>
 109                 This variable is the relative path from this Makefile to the
 110                 top directory of your project's source code.  For example, if
 111                 your source code is in /tmp/src, then the Makefile in
 112                 /tmp/src/jump/high would set LEVEL to "../..".
 113         </dl>
 114
 115         <h3> Variables for Building Subdirectories</h3>
 116         <dl compact>
 117                 <dt>DIRS
 118                 <dd>
 119                 This is a space separated list of subdirectories that should be
 120                 built.  They will be built, one at a time, in the order
 121                 specified.
 122                 <p>
 123
 124                 <dt>PARALLEL_DIRS
 125                 <dd>
 126                 This is a list of directories that can be built in parallel.
 127                 These will be built after the directories in DIRS have been
 128                 built.
 129                 <p>
 130
 131                 <dt>OPTIONAL_DIRS
 132                 <dd>
 133                 This is a list of directories that can be built if they exist,
 134                 but will not cause an error if they do not exist.  They are
 135                 built serially in the order in which they are listed.
 136         </dl>
 137
 138         <h3> Variables for Building Libraries</h3>
 139         <dl compact>
 140                 <dt>LIBRARYNAME
 141                 <dd>
 142                 This variable contains the base name of the library that will
 143                 be built.  For example, to build a library named
 144                 <tt>libsample.a</tt>, LIBRARYNAME should be set to
 145                 <tt>sample</tt>.
 146                 <p>
 147
 148                 <dt>BUILD_ARCHIVE
 149                 <dd>
 150                 By default, a library is a <tt>.o</tt> file that is linked
 151                 directly into a program.  However, if you set the BUILD_ARCHIVE
 152                 variable, an archive library (sometimes known as a static
 153                 library) will be built instead.
 154                 <p>
 155
 156                 <dt>SHARED_LIBRARY
 157                 <dd>
 158                 If SHARED_LIBRARY is defined in your Makefile, then the
 159                 Makefiles will generate a shared (or dynamic) library.
 160         </dl>
 161
 162         <h3> Variables for Building Programs</h3>
 163         <dl compact>
 164                 <dt>TOOLNAME
 165                 <dd>
 166                 This variable contains the name of the program that will
 167                 be built.  For example, to build an executable named
 168                 <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
 169                 <p>
 170
 171                 <dt>USEDLIBS
 172                 <dd>
 173                 This variable holds a space separated list of libraries that
 174                 should be linked into the program.  These libraries must either
 175                 be LLVM libraries or libraries that come from your <b>lib</b>
 176                 directory.  The libraries must be specified by their base name.
 177                 For example, to link libsample.a, you would set USEDLIBS to
 178                 <tt>sample</tt>.
 179                 <p>
 180         </dl>
 181
 182         <h3> Miscellaneous Variables</h3>
 183         <dl compact>
 184                 <dt>ExtraSource
 185                 <dd>
 186                 This variable contains a space separated list of extra source
 187                 files that needs to be built.  It is useful for including the
 188                 output of Lex and Yacc programs.
 189                 <p>
 190
 191                 <dt>CFLAGS
 192                 <dt>CPPFLAGS
 193                 <dd>
 194                 This variable can be used to add options to the C and C++
 195                 compiler, respectively.  It is typically used to add options
 196                 that tell the compiler the location of additional directories
 197                 to search for header files.
 198                 <p>
 199                 It is highly suggested that you append to these variable as
 200                 opposed to overwriting them.  The master Makefiles may already
 201                 have useful options in them that you may not want to overwrite.
 202                 <p>
 203         </dl>
 204
 205 </body>
 206 </html>