docs/Projects.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <title>Creating an LLVM Project</title>
   6   <link rel="stylesheet" href="llvm.css" type="text/css">
   7 </head>
   8 <body>
   9
  10 <div class="doc_title">Creating an LLVM Project</div>
  11
  12 <ol>
  13 <li><a href="#overview">Overview</a></li>
  14 <li><a href="#create">Create a project from the Sample Project</a></li>
  15 <li><a href="#source">Source tree layout</a></li>
  16 <li><a href="#makefiles">Writing LLVM-style Makefiles</a>
  17   <ol>
  18   <li><a href="#reqVars">Required Variables</a></li>
  19   <li><a href="#varsBuildDir">Variables for Building Subdirectories</a></li>
  20   <li><a href="#varsBuildLib">Variables for Building Libraries</a></li>
  21   <li><a href="#varsBuildProg">Variables for Building Programs</a></li>
  22   <li><a href="#miscVars">Miscellaneous Variables</a></li>
  23   </ol></li>
  24 <li><a href="#objcode">Placement of object code</a></li>
  25 <li><a href="#help">Further help</a></li>
  26 </ol>
  27
  28 <div class="doc_author">
  29   <p>Written by John Criswell</p>
  30 </div>
  31
  32 <!-- *********************************************************************** -->
  33 <div class="doc_section"><a name="overview">Overview</a></div>
  34 <!-- *********************************************************************** -->
  35
  36 <div class="doc_text">
  37
  38 <p>The LLVM build system is designed to facilitate the building of third party
  39 projects that use LLVM header files, libraries, and tools.  In order to use
  40 these facilities, a Makefile from a project must do the following things:</p>
  41
  42 <ol>
  43   <li>Set <tt>make</tt> variables. There are several variables that a Makefile
  44   needs to set to use the LLVM build system:
  45   <ul>
  46     <li><tt>PROJECT_NAME</tt> - The name by which your project is known.</li>
  47     <li><tt>LLVM_SRC_ROOT</tt> - The root of the LLVM source tree.</li>
  48     <li><tt>LLVM_OBJ_ROOT</tt> - The root of the LLVM object tree.</li>
  49     <li><tt>PROJ_SRC_ROOT</tt> - The root of the project's source tree.</li>
  50     <li><tt>PROJ_OBJ_ROOT</tt> - The root of the project's object tree.</li>
  51     <li><tt>PROJ_INSTALL_ROOT</tt> - The root installation directory.</li>
  52     <li><tt>LEVEL</tt> - The relative path from the current directory to the
  53     project's root ($PROJ_OBJ_ROOT).</li>
  54   </ul></li>
  55   <li>Include <tt>Makefile.config</tt> from <tt>$(LLVM_OBJ_ROOT)</tt>.</li>
  56   <li>Include <tt>Makefile.rules</tt> from <tt>$(LLVM_SRC_ROOT)</tt>.</li>
  57 </ol>
  58
  59 <p>There are two ways that you can set all of these variables:</p>
  60 <ol>
  61   <li>You can write your own Makefiles which hard-code these values.</li>
  62   <li>You can use the pre-made LLVM sample project. This sample project
  63   includes Makefiles, a configure script that can be used to configure the
  64   location of LLVM, and the ability to support multiple object directories
  65   from a single source directory.</li>
  66 </ol>
  67
  68 <p>This document assumes that you will base your project on the LLVM sample
  69 project found in <tt>llvm/projects/sample</tt>.  If you want to devise your own
  70 build system, studying the sample project and LLVM Makefiles will probably
  71 provide enough information on how to write your own Makefiles.</p>
  72
  73 </div>
  74
  75 <!-- *********************************************************************** -->
  76 <div class="doc_section">
  77   <a name="create">Create a Project from the Sample Project</a>
  78 </div>
  79 <!-- *********************************************************************** -->
  80
  81 <div class="doc_text">
  82
  83 <p>Follow these simple steps to start your project:</p>
  84
  85 <ol>
  86 <li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
  87 choosing.  You can place it anywhere you like.  Rename the directory to match
  88 the name of your project.</li>
  89
  90 <li>Add your source code and Makefiles to your source tree.</li>
  91
  92 <li>If you want your Makefiles to be configured by the <tt>configure</tt>
  93 script, or if you want to support multiple object directories, add your
  94 Makefiles to the <tt>configure</tt> script by adding them into the
  95 <tt>autoconf/configure.ac</tt> file.  The macro <tt>AC_CONFIG_MAKEFILE</tt> will
  96 copy a file, unmodified, from the source directory to the object directory.</li>
  97
  98 <li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
  99 configure script with these commands:
 100
 101 <div class="doc_code">
 102 <p><tt>% cd autoconf<br>
 103        % autoconf -o ../configure</tt></p>
 104 </div>
 105
 106 <p>You must be using Autoconf version 2.57 or higher.</p></li>
 107
 108 <li>Run <tt>configure</tt> in the directory in which you want to place
 109 object code.  Use the following options to tell your project where it
 110 can find LLVM:
 111
 112   <dl>
 113     <dt><tt>--with-llvmsrc=&lt;directory&gt;</tt>
 114     <dd>
 115     Tell your project where the LLVM source tree is located.
 116     <p>
 117     <dt><tt>--with-llvmobj=&lt;directory&gt;</tt>
 118     <dd>
 119     Tell your project where the LLVM object tree is located.
 120   </dl>
 121 </ol>
 122
 123 <p>That's it!  Now all you have to do is type <tt>gmake</tt> in the root of
 124 your object directory, and your project should build.</p>
 125
 126 </div>
 127
 128 <!-- *********************************************************************** -->
 129 <div class="doc_section">
 130   <a name="source">Source Tree Layout</a>
 131 </div>
 132 <!-- *********************************************************************** -->
 133
 134 <div class="doc_text">
 135
 136 <p>In order to use the LLVM build system, you will want to organize your
 137 source code so that it can benefit from the build system's features.
 138 Mainly, you want your source tree layout to look similar to the LLVM
 139 source tree layout.  The best way to do this is to just copy the
 140 project tree from <tt>llvm/projects/sample</tt> and modify it to meet
 141 your needs, but you can certainly add to it if you want.</p>
 142
 143 <p>Underneath your top level directory, you should have the following
 144 directories:</p>
 145
 146 <dl>
 147   <dt><b>lib</b>
 148   <dd>
 149   This subdirectory should contain all of your library source
 150   code.  For each library that you build, you will have one
 151   directory in <b>lib</b> that will contain that library's source
 152   code.
 153
 154   <p>
 155   Libraries can be object files, archives, or dynamic libraries.
 156   The <b>lib</b> directory is just a convenient place for libraries
 157   as it places them all in a directory from which they can be linked
 158   later.
 159
 160   <dt><b>include</b>
 161   <dd>
 162   This subdirectory should contain any header files that are
 163   global to your project.  By global, we mean that they are used
 164   by more than one library or executable of your project.
 165   <p>
 166   By placing your header files in <b>include</b>, they will be
 167   found automatically by the LLVM build system.  For example, if
 168   you have a file <b>include/jazz/note.h</b>, then your source
 169   files can include it simply with <b>#include "jazz/note.h"</b>.
 170
 171   <dt><b>tools</b>
 172   <dd>
 173   This subdirectory should contain all of your source
 174   code for executables.  For each program that you build, you
 175   will have one directory in <b>tools</b> that will contain that
 176   program's source code.
 177   <p>
 178
 179   <dt><b>test</b>
 180   <dd>
 181   This subdirectory should contain tests that verify that your code
 182   works correctly.  Automated tests are especially useful.
 183   <p>
 184   Currently, the LLVM build system provides basic support for tests.
 185   The LLVM system provides the following:
 186   <ul>
 187     <li>
 188     LLVM provides a tcl procedure that is used by Dejagnu to run
 189     tests.  It can be found in <tt>llvm/lib/llvm-dg.exp</tt>.  This
 190     test procedure uses RUN lines in the actual test case to determine
 191     how to run the test.  See the <a
 192     href="TestingGuide.html">TestingGuide</a> for more details. You
 193     can easily write Makefile support similar to the Makefiles in <tt>llvm/test</tt>
 194     to use Dejagnu to run your project's tests.</li>
 195
 196     <p>
 197
 198     <li>
 199     LLVM contains an optional package called <tt>llvm-test</tt>
 200     which provides benchmarks and programs that are known to compile with the
 201     LLVM GCC front ends.  You can use these
 202     programs to test your code, gather statistics information, and
 203     compare it to the current LLVM performance statistics.
 204     <p>
 205     Currently, there is no way to hook your tests directly into the
 206     <tt>llvm/test</tt> testing harness.  You will simply
 207     need to find a way to use the source provided within that directory
 208     on your own.
 209   </ul>
 210 </dl>
 211
 212 <p>Typically, you will want to build your <b>lib</b> directory first followed by
 213 your <b>tools</b> directory.</p>
 214
 215 </div>
 216
 217 <!-- *********************************************************************** -->
 218 <div class="doc_section">
 219   <a name="makefiles">Writing LLVM Style Makefiles</a>
 220 </div>
 221 <!-- *********************************************************************** -->
 222
 223 <div class="doc_text">
 224
 225 <p>The LLVM build system provides a convenient way to build libraries and
 226 executables.  Most of your project Makefiles will only need to define a few
 227 variables.  Below is a list of the variables one can set and what they can
 228 do:</p>
 229
 230 </div>
 231
 232 <!-- ======================================================================= -->
 233 <div class="doc_subsection">
 234   <a name="reqVars">Required Variables</a>
 235 </div>
 236
 237 <div class="doc_text">
 238
 239 <dl>
 240   <dt>LEVEL
 241   <dd>
 242   This variable is the relative path from this Makefile to the
 243   top directory of your project's source code.  For example, if
 244   your source code is in <tt>/tmp/src</tt>, then the Makefile in
 245   <tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
 246 </dl>
 247
 248 </div>
 249
 250 <!-- ======================================================================= -->
 251 <div class="doc_subsection">
 252   <a name="varsBuildDir">Variables for Building Subdirectories</a>
 253 </div>
 254
 255 <div class="doc_text">
 256
 257 <dl>
 258   <dt>DIRS
 259   <dd>
 260   This is a space separated list of subdirectories that should be
 261   built.  They will be built, one at a time, in the order
 262   specified.
 263   <p>
 264
 265   <dt>PARALLEL_DIRS
 266   <dd>
 267   This is a list of directories that can be built in parallel.
 268   These will be built after the directories in DIRS have been
 269   built.
 270   <p>
 271
 272   <dt>OPTIONAL_DIRS
 273   <dd>
 274   This is a list of directories that can be built if they exist,
 275   but will not cause an error if they do not exist.  They are
 276   built serially in the order in which they are listed.
 277 </dl>
 278
 279 </div>
 280
 281 <!-- ======================================================================= -->
 282 <div class="doc_subsection">
 283   <a name="varsBuildLib">Variables for Building Libraries</a>
 284 </div>
 285
 286 <div class="doc_text">
 287
 288 <dl>
 289   <dt>LIBRARYNAME
 290   <dd>
 291   This variable contains the base name of the library that will
 292   be built.  For example, to build a library named
 293   <tt>libsample.a</tt>, LIBRARYNAME should be set to
 294   <tt>sample</tt>.
 295   <p>
 296
 297   <dt>BUILD_ARCHIVE
 298   <dd>
 299   By default, a library is a <tt>.o</tt> file that is linked
 300   directly into a program.  To build an archive (also known as
 301   a static library), set the BUILD_ARCHIVE variable.
 302   <p>
 303
 304   <dt>SHARED_LIBRARY
 305   <dd>
 306   If SHARED_LIBRARY is defined in your Makefile, a shared
 307   (or dynamic) library will be built.
 308 </dl>
 309
 310 </div>
 311
 312 <!-- ======================================================================= -->
 313 <div class="doc_subsection">
 314   <a name="varsBuildProg">Variables for Building Programs</a>
 315 </div>
 316
 317 <div class="doc_text">
 318
 319 <dl>
 320   <dt>TOOLNAME
 321   <dd>
 322   This variable contains the name of the program that will
 323   be built.  For example, to build an executable named
 324   <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
 325   <p>
 326
 327   <dt>USEDLIBS
 328   <dd>
 329   This variable holds a space separated list of libraries that
 330   should be linked into the program.  These libraries must either
 331   be LLVM libraries or libraries that come from your <b>lib</b>
 332   directory.  The libraries must be specified by their base name.
 333   For example, to link libsample.a, you would set USEDLIBS to
 334   <tt>sample</tt>.
 335   <p>
 336   Note that this works only for statically linked libraries.
 337   <p>
 338
 339   <dt>LIBS
 340   <dd>
 341   To link dynamic libraries, add <tt>-l&lt;library base name&gt;</tt> to
 342   the LIBS variable.  The LLVM build system will look in the same places
 343   for dynamic libraries as it does for static libraries.
 344   <p>
 345   For example, to link <tt>libsample.so</tt>, you would have the
 346   following line in your <tt>Makefile</tt>:
 347   <p>
 348   <tt>
 349   LIBS += -lsample
 350   </tt>
 351 </dl>
 352
 353 </div>
 354
 355 <!-- ======================================================================= -->
 356 <div class="doc_subsection">
 357   <a name="miscVars">Miscellaneous Variables</a>
 358 </div>
 359
 360 <div class="doc_text">
 361
 362 <dl>
 363   <dt>ExtraSource
 364   <dd>
 365   This variable contains a space separated list of extra source
 366   files that need to be built.  It is useful for including the
 367   output of Lex and Yacc programs.
 368   <p>
 369
 370   <dt>CFLAGS
 371   <dt>CPPFLAGS
 372   <dd>
 373   This variable can be used to add options to the C and C++
 374   compiler, respectively.  It is typically used to add options
 375   that tell the compiler the location of additional directories
 376   to search for header files.
 377   <p>
 378   It is highly suggested that you append to CFLAGS and CPPFLAGS as
 379   opposed to overwriting them.  The master Makefiles may already
 380   have useful options in them that you may not want to overwrite.
 381   <p>
 382 </dl>
 383
 384 </div>
 385
 386 <!-- *********************************************************************** -->
 387 <div class="doc_section">
 388   <a name="objcode">Placement of Object Code</a>
 389 </div>
 390 <!-- *********************************************************************** -->
 391
 392 <div class="doc_text">
 393
 394 <p>The final location of built libraries and executables will depend upon
 395 whether you do a Debug, Release, or Profile build.</p>
 396
 397 <dl>
 398   <dt>Libraries
 399   <dd>
 400   All libraries (static and dynamic) will be stored in
 401   <tt>BUILD_OBJ_ROOT/lib/&lt;type&gt;</tt>, where type is <tt>Debug</tt>,
 402   <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or
 403   profiled build, respectively.<p>
 404
 405   <dt>Executables
 406   <dd>All executables will be stored in
 407   <tt>BUILD_OBJ_ROOT/tools/&lt;type&gt;</tt>, where type is <tt>Debug</tt>,
 408   <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
 409   build, respectively.
 410 </dl>
 411
 412 </div>
 413
 414 <!-- *********************************************************************** -->
 415 <div class="doc_section">
 416   <a name="help">Further Help</a>
 417 </div>
 418 <!-- *********************************************************************** -->
 419
 420 <div class="doc_text">
 421
 422 <p>If you have any questions or need any help creating an LLVM project,
 423 the LLVM team would be more than happy to help.  You can always post your
 424 questions to the <a
 425 href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
 426 Mailing List</a>.</p>
 427
 428 </div>
 429
 430 <!-- *********************************************************************** -->
 431 <hr>
 432 <address>
 433   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 434   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 435   <a href="http://validator.w3.org/check/referer"><img
 436   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
 437
 438   <a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
 439   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
 440   <br>
 441   Last modified: $Date$
 442 </address>
 443
 444 </body>
 445 </html>