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