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 project to be configured with the <tt>configure</tt> script
  93 then you need to edit <tt>autoconf/configure.ac</tt> as follows:
  94   <ul>
  95     <li><b>AC_INIT</b>. Place the name of your project, its version number and
  96     a contact email address for your project as the arguments to this macro</li>
  97     <li><b>AC_CONFIG_AUC_DIR</tt>. If your project isn't in the
  98     <tt>llvm/projects</tt> directory then you might need to adjust this so that
  99     it specifies a relative path to the <tt>llvm/autoconf</tt> directory.</li>
 100     <li><b>LLVM_CONFIG_PROJECT</b>. Just leave this alone.</li>
 101     <li><b>AC_CONFIG_SRCDIR</b>. Specify a path to a file name that identifies
 102     your project; or just leave it at <tt>Makefile.config.in</tt></li>
 103     <li><b>AC_CONFIG_FILES</b>. Do not change.</li>
 104     <li><b>AC_CONFIG_MAKEFILE</b>. Use one of these macros for each Makefile
 105     that your project uses. This macro arranges for your makefiles to be copied
 106     from the source directory, unmodified, to the build directory.</li>
 107   </ul>
 108 </li>
 109
 110 <li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
 111 configure script with these commands:
 112
 113 <div class="doc_code">
 114 <p><tt>% cd autoconf<br>
 115        % AutoRegen.sh</tt></p>
 116 </div>
 117
 118 <p>You must be using Autoconf version 2.59 or later and your aclocal version
 119 should 1.9 or later.</p></li>
 120
 121 <li>Run <tt>configure</tt> in the directory in which you want to place
 122 object code.  Use the following options to tell your project where it
 123 can find LLVM:
 124
 125   <dl>
 126     <dt><tt>--with-llvmsrc=&lt;directory&gt;</tt></dt>
 127     <dd>Tell your project where the LLVM source tree is located.</dd>
 128     <dt><br/><tt>--with-llvmobj=&lt;directory&gt;</tt></dt>
 129     <dd>Tell your project where the LLVM object tree is located.</dd>
 130     <dt><br/><tt>--prefix=&lt;directory&gt;</tt></dt>
 131     <dd>Tell your project where it should get installed.</dd>
 132   </dl>
 133 </ol>
 134
 135 <p>That's it!  Now all you have to do is type <tt>gmake</tt> (or <tt>make</tt>
 136 if your on a GNU/Linux system) in the root of your object directory, and your
 137 project should build.</p>
 138
 139 </div>
 140
 141 <!-- *********************************************************************** -->
 142 <div class="doc_section">
 143   <a name="source">Source Tree Layout</a>
 144 </div>
 145 <!-- *********************************************************************** -->
 146
 147 <div class="doc_text">
 148
 149 <p>In order to use the LLVM build system, you will want to organize your
 150 source code so that it can benefit from the build system's features.
 151 Mainly, you want your source tree layout to look similar to the LLVM
 152 source tree layout.  The best way to do this is to just copy the
 153 project tree from <tt>llvm/projects/sample</tt> and modify it to meet
 154 your needs, but you can certainly add to it if you want.</p>
 155
 156 <p>Underneath your top level directory, you should have the following
 157 directories:</p>
 158
 159 <dl>
 160   <dt><b>lib</b>
 161   <dd>
 162   This subdirectory should contain all of your library source
 163   code.  For each library that you build, you will have one
 164   directory in <b>lib</b> that will contain that library's source
 165   code.
 166
 167   <p>
 168   Libraries can be object files, archives, or dynamic libraries.
 169   The <b>lib</b> directory is just a convenient place for libraries
 170   as it places them all in a directory from which they can be linked
 171   later.
 172
 173   <dt><b>include</b>
 174   <dd>
 175   This subdirectory should contain any header files that are
 176   global to your project.  By global, we mean that they are used
 177   by more than one library or executable of your project.
 178   <p>
 179   By placing your header files in <b>include</b>, they will be
 180   found automatically by the LLVM build system.  For example, if
 181   you have a file <b>include/jazz/note.h</b>, then your source
 182   files can include it simply with <b>#include "jazz/note.h"</b>.
 183
 184   <dt><b>tools</b>
 185   <dd>
 186   This subdirectory should contain all of your source
 187   code for executables.  For each program that you build, you
 188   will have one directory in <b>tools</b> that will contain that
 189   program's source code.
 190   <p>
 191
 192   <dt><b>test</b>
 193   <dd>
 194   This subdirectory should contain tests that verify that your code
 195   works correctly.  Automated tests are especially useful.
 196   <p>
 197   Currently, the LLVM build system provides basic support for tests.
 198   The LLVM system provides the following:
 199   <ul>
 200     <li>
 201     LLVM provides a tcl procedure that is used by Dejagnu to run
 202     tests.  It can be found in <tt>llvm/lib/llvm-dg.exp</tt>.  This
 203     test procedure uses RUN lines in the actual test case to determine
 204     how to run the test.  See the <a
 205     href="TestingGuide.html">TestingGuide</a> for more details. You
 206     can easily write Makefile support similar to the Makefiles in <tt>llvm/test</tt>
 207     to use Dejagnu to run your project's tests.</li>
 208
 209     <p>
 210
 211     <li>
 212     LLVM contains an optional package called <tt>llvm-test</tt>
 213     which provides benchmarks and programs that are known to compile with the
 214     LLVM GCC front ends.  You can use these
 215     programs to test your code, gather statistics information, and
 216     compare it to the current LLVM performance statistics.
 217     <p>
 218     Currently, there is no way to hook your tests directly into the
 219     <tt>llvm/test</tt> testing harness.  You will simply
 220     need to find a way to use the source provided within that directory
 221     on your own.
 222   </ul>
 223 </dl>
 224
 225 <p>Typically, you will want to build your <b>lib</b> directory first followed by
 226 your <b>tools</b> directory.</p>
 227
 228 </div>
 229
 230 <!-- *********************************************************************** -->
 231 <div class="doc_section">
 232   <a name="makefiles">Writing LLVM Style Makefiles</a>
 233 </div>
 234 <!-- *********************************************************************** -->
 235
 236 <div class="doc_text">
 237
 238 <p>The LLVM build system provides a convenient way to build libraries and
 239 executables.  Most of your project Makefiles will only need to define a few
 240 variables.  Below is a list of the variables one can set and what they can
 241 do:</p>
 242
 243 </div>
 244
 245 <!-- ======================================================================= -->
 246 <div class="doc_subsection">
 247   <a name="reqVars">Required Variables</a>
 248 </div>
 249
 250 <div class="doc_text">
 251
 252 <dl>
 253   <dt>LEVEL
 254   <dd>
 255   This variable is the relative path from this Makefile to the
 256   top directory of your project's source code.  For example, if
 257   your source code is in <tt>/tmp/src</tt>, then the Makefile in
 258   <tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
 259 </dl>
 260
 261 </div>
 262
 263 <!-- ======================================================================= -->
 264 <div class="doc_subsection">
 265   <a name="varsBuildDir">Variables for Building Subdirectories</a>
 266 </div>
 267
 268 <div class="doc_text">
 269
 270 <dl>
 271   <dt>DIRS
 272   <dd>
 273   This is a space separated list of subdirectories that should be
 274   built.  They will be built, one at a time, in the order
 275   specified.
 276   <p>
 277
 278   <dt>PARALLEL_DIRS
 279   <dd>
 280   This is a list of directories that can be built in parallel.
 281   These will be built after the directories in DIRS have been
 282   built.
 283   <p>
 284
 285   <dt>OPTIONAL_DIRS
 286   <dd>
 287   This is a list of directories that can be built if they exist,
 288   but will not cause an error if they do not exist.  They are
 289   built serially in the order in which they are listed.
 290 </dl>
 291
 292 </div>
 293
 294 <!-- ======================================================================= -->
 295 <div class="doc_subsection">
 296   <a name="varsBuildLib">Variables for Building Libraries</a>
 297 </div>
 298
 299 <div class="doc_text">
 300
 301 <dl>
 302   <dt>LIBRARYNAME
 303   <dd>
 304   This variable contains the base name of the library that will
 305   be built.  For example, to build a library named
 306   <tt>libsample.a</tt>, LIBRARYNAME should be set to
 307   <tt>sample</tt>.
 308   <p>
 309
 310   <dt>BUILD_ARCHIVE
 311   <dd>
 312   By default, a library is a <tt>.o</tt> file that is linked
 313   directly into a program.  To build an archive (also known as
 314   a static library), set the BUILD_ARCHIVE variable.
 315   <p>
 316
 317   <dt>SHARED_LIBRARY
 318   <dd>
 319   If SHARED_LIBRARY is defined in your Makefile, a shared
 320   (or dynamic) library will be built.
 321 </dl>
 322
 323 </div>
 324
 325 <!-- ======================================================================= -->
 326 <div class="doc_subsection">
 327   <a name="varsBuildProg">Variables for Building Programs</a>
 328 </div>
 329
 330 <div class="doc_text">
 331
 332 <dl>
 333   <dt>TOOLNAME
 334   <dd>
 335   This variable contains the name of the program that will
 336   be built.  For example, to build an executable named
 337   <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
 338   <p>
 339
 340   <dt>USEDLIBS
 341   <dd>
 342   This variable holds a space separated list of libraries that
 343   should be linked into the program.  These libraries must either
 344   be LLVM libraries or libraries that come from your <b>lib</b>
 345   directory.  The libraries must be specified by their base name.
 346   For example, to link libsample.a, you would set USEDLIBS to
 347   <tt>sample</tt>.
 348   <p>
 349   Note that this works only for statically linked libraries.
 350   <p>
 351
 352   <dt>LIBS
 353   <dd>
 354   To link dynamic libraries, add <tt>-l&lt;library base name&gt;</tt> to
 355   the LIBS variable.  The LLVM build system will look in the same places
 356   for dynamic libraries as it does for static libraries.
 357   <p>
 358   For example, to link <tt>libsample.so</tt>, you would have the
 359   following line in your <tt>Makefile</tt>:
 360   <p>
 361   <tt>
 362   LIBS += -lsample
 363   </tt>
 364 </dl>
 365
 366 </div>
 367
 368 <!-- ======================================================================= -->
 369 <div class="doc_subsection">
 370   <a name="miscVars">Miscellaneous Variables</a>
 371 </div>
 372
 373 <div class="doc_text">
 374
 375 <dl>
 376   <dt>ExtraSource
 377   <dd>
 378   This variable contains a space separated list of extra source
 379   files that need to be built.  It is useful for including the
 380   output of Lex and Yacc programs.
 381   <p>
 382
 383   <dt>CFLAGS
 384   <dt>CPPFLAGS
 385   <dd>
 386   This variable can be used to add options to the C and C++
 387   compiler, respectively.  It is typically used to add options
 388   that tell the compiler the location of additional directories
 389   to search for header files.
 390   <p>
 391   It is highly suggested that you append to CFLAGS and CPPFLAGS as
 392   opposed to overwriting them.  The master Makefiles may already
 393   have useful options in them that you may not want to overwrite.
 394   <p>
 395 </dl>
 396
 397 </div>
 398
 399 <!-- *********************************************************************** -->
 400 <div class="doc_section">
 401   <a name="objcode">Placement of Object Code</a>
 402 </div>
 403 <!-- *********************************************************************** -->
 404
 405 <div class="doc_text">
 406
 407 <p>The final location of built libraries and executables will depend upon
 408 whether you do a Debug, Release, or Profile build.</p>
 409
 410 <dl>
 411   <dt>Libraries
 412   <dd>
 413   All libraries (static and dynamic) will be stored in
 414   <tt>PROJ_OBJ_ROOT/&lt;type&gt;/lib</tt>, where type is <tt>Debug</tt>,
 415   <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or
 416   profiled build, respectively.<p>
 417
 418   <dt>Executables
 419   <dd>All executables will be stored in
 420   <tt>PROJ_OBJ_ROOT/&lt;type&gt;/bin</tt>, where type is <tt>Debug</tt>,
 421   <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
 422   build, respectively.
 423 </dl>
 424
 425 </div>
 426
 427 <!-- *********************************************************************** -->
 428 <div class="doc_section">
 429   <a name="help">Further Help</a>
 430 </div>
 431 <!-- *********************************************************************** -->
 432
 433 <div class="doc_text">
 434
 435 <p>If you have any questions or need any help creating an LLVM project,
 436 the LLVM team would be more than happy to help.  You can always post your
 437 questions to the <a
 438 href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
 439 Mailing List</a>.</p>
 440
 441 </div>
 442
 443 <!-- *********************************************************************** -->
 444 <hr>
 445 <address>
 446   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 447   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 448   <a href="http://validator.w3.org/check/referer"><img
 449   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
 450
 451   <a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
 452   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
 453   <br>
 454   Last modified: $Date$
 455 </address>
 456
 457 </body>
 458 </html>