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</b>. 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
 207     <tt>llvm/test</tt> to use Dejagnu to run your project's tests.<br/></li>
 208     <li>
 209     LLVM contains an optional package called <tt>llvm-test</tt>
 210     which provides benchmarks and programs that are known to compile with the
 211     LLVM GCC front ends.  You can use these
 212     programs to test your code, gather statistics information, and
 213     compare it to the current LLVM performance statistics.
 214     <br/>Currently, there is no way to hook your tests directly into the
 215     <tt>llvm/test</tt> testing harness.  You will simply
 216     need to find a way to use the source provided within that directory
 217     on your own.
 218   </ul>
 219 </dl>
 220
 221 <p>Typically, you will want to build your <b>lib</b> directory first followed by
 222 your <b>tools</b> directory.</p>
 223
 224 </div>
 225
 226 <!-- *********************************************************************** -->
 227 <div class="doc_section">
 228   <a name="makefiles">Writing LLVM Style Makefiles</a>
 229 </div>
 230 <!-- *********************************************************************** -->
 231
 232 <div class="doc_text">
 233
 234 <p>The LLVM build system provides a convenient way to build libraries and
 235 executables.  Most of your project Makefiles will only need to define a few
 236 variables.  Below is a list of the variables one can set and what they can
 237 do:</p>
 238
 239 </div>
 240
 241 <!-- ======================================================================= -->
 242 <div class="doc_subsection">
 243   <a name="reqVars">Required Variables</a>
 244 </div>
 245
 246 <div class="doc_text">
 247
 248 <dl>
 249   <dt>LEVEL
 250   <dd>
 251   This variable is the relative path from this Makefile to the
 252   top directory of your project's source code.  For example, if
 253   your source code is in <tt>/tmp/src</tt>, then the Makefile in
 254   <tt>/tmp/src/jump/high</tt> would set <tt>LEVEL</tt> to <tt>"../.."</tt>.
 255 </dl>
 256
 257 </div>
 258
 259 <!-- ======================================================================= -->
 260 <div class="doc_subsection">
 261   <a name="varsBuildDir">Variables for Building Subdirectories</a>
 262 </div>
 263
 264 <div class="doc_text">
 265
 266 <dl>
 267   <dt>DIRS
 268   <dd>
 269   This is a space separated list of subdirectories that should be
 270   built.  They will be built, one at a time, in the order
 271   specified.
 272   <p>
 273
 274   <dt>PARALLEL_DIRS
 275   <dd>
 276   This is a list of directories that can be built in parallel.
 277   These will be built after the directories in DIRS have been
 278   built.
 279   <p>
 280
 281   <dt>OPTIONAL_DIRS
 282   <dd>
 283   This is a list of directories that can be built if they exist,
 284   but will not cause an error if they do not exist.  They are
 285   built serially in the order in which they are listed.
 286 </dl>
 287
 288 </div>
 289
 290 <!-- ======================================================================= -->
 291 <div class="doc_subsection">
 292   <a name="varsBuildLib">Variables for Building Libraries</a>
 293 </div>
 294
 295 <div class="doc_text">
 296
 297 <dl>
 298   <dt>LIBRARYNAME
 299   <dd>
 300   This variable contains the base name of the library that will
 301   be built.  For example, to build a library named
 302   <tt>libsample.a</tt>, LIBRARYNAME should be set to
 303   <tt>sample</tt>.
 304   <p>
 305
 306   <dt>BUILD_ARCHIVE
 307   <dd>
 308   By default, a library is a <tt>.o</tt> file that is linked
 309   directly into a program.  To build an archive (also known as
 310   a static library), set the BUILD_ARCHIVE variable.
 311   <p>
 312
 313   <dt>SHARED_LIBRARY
 314   <dd>
 315   If SHARED_LIBRARY is defined in your Makefile, a shared
 316   (or dynamic) library will be built.
 317 </dl>
 318
 319 </div>
 320
 321 <!-- ======================================================================= -->
 322 <div class="doc_subsection">
 323   <a name="varsBuildProg">Variables for Building Programs</a>
 324 </div>
 325
 326 <div class="doc_text">
 327
 328 <dl>
 329   <dt>TOOLNAME
 330   <dd>
 331   This variable contains the name of the program that will
 332   be built.  For example, to build an executable named
 333   <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
 334   <p>
 335
 336   <dt>USEDLIBS
 337   <dd>
 338   This variable holds a space separated list of libraries that
 339   should be linked into the program.  These libraries must either
 340   be LLVM libraries or libraries that come from your <b>lib</b>
 341   directory.  The libraries must be specified by their base name.
 342   For example, to link libsample.a, you would set USEDLIBS to
 343   <tt>sample</tt>.
 344   <p>
 345   Note that this works only for statically linked libraries.
 346   <p>
 347
 348   <dt>LIBS
 349   <dd>
 350   To link dynamic libraries, add <tt>-l&lt;library base name&gt;</tt> to
 351   the LIBS variable.  The LLVM build system will look in the same places
 352   for dynamic libraries as it does for static libraries.
 353   <p>
 354   For example, to link <tt>libsample.so</tt>, you would have the
 355   following line in your <tt>Makefile</tt>:
 356   <p>
 357   <tt>
 358   LIBS += -lsample
 359   </tt>
 360 </dl>
 361
 362 </div>
 363
 364 <!-- ======================================================================= -->
 365 <div class="doc_subsection">
 366   <a name="miscVars">Miscellaneous Variables</a>
 367 </div>
 368
 369 <div class="doc_text">
 370
 371 <dl>
 372   <dt>ExtraSource
 373   <dd>
 374   This variable contains a space separated list of extra source
 375   files that need to be built.  It is useful for including the
 376   output of Lex and Yacc programs.
 377   <p>
 378
 379   <dt>CFLAGS
 380   <dt>CPPFLAGS
 381   <dd>
 382   This variable can be used to add options to the C and C++
 383   compiler, respectively.  It is typically used to add options
 384   that tell the compiler the location of additional directories
 385   to search for header files.
 386   <p>
 387   It is highly suggested that you append to CFLAGS and CPPFLAGS as
 388   opposed to overwriting them.  The master Makefiles may already
 389   have useful options in them that you may not want to overwrite.
 390   <p>
 391 </dl>
 392
 393 </div>
 394
 395 <!-- *********************************************************************** -->
 396 <div class="doc_section">
 397   <a name="objcode">Placement of Object Code</a>
 398 </div>
 399 <!-- *********************************************************************** -->
 400
 401 <div class="doc_text">
 402
 403 <p>The final location of built libraries and executables will depend upon
 404 whether you do a Debug, Release, or Profile build.</p>
 405
 406 <dl>
 407   <dt>Libraries
 408   <dd>
 409   All libraries (static and dynamic) will be stored in
 410   <tt>PROJ_OBJ_ROOT/&lt;type&gt;/lib</tt>, where type is <tt>Debug</tt>,
 411   <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or
 412   profiled build, respectively.<p>
 413
 414   <dt>Executables
 415   <dd>All executables will be stored in
 416   <tt>PROJ_OBJ_ROOT/&lt;type&gt;/bin</tt>, where type is <tt>Debug</tt>,
 417   <tt>Release</tt>, or <tt>Profile</tt> for a debug, optimized, or profiled
 418   build, respectively.
 419 </dl>
 420
 421 </div>
 422
 423 <!-- *********************************************************************** -->
 424 <div class="doc_section">
 425   <a name="help">Further Help</a>
 426 </div>
 427 <!-- *********************************************************************** -->
 428
 429 <div class="doc_text">
 430
 431 <p>If you have any questions or need any help creating an LLVM project,
 432 the LLVM team would be more than happy to help.  You can always post your
 433 questions to the <a
 434 href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
 435 Mailing List</a>.</p>
 436
 437 </div>
 438
 439 <!-- *********************************************************************** -->
 440 <hr>
 441 <address>
 442   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 443   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 444   <a href="http://validator.w3.org/check/referer"><img
 445   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
 446
 447   <a href="mailto:criswell@uiuc.edu">John Criswell</a><br>
 448   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
 449   <br>
 450   Last modified: $Date$
 451 </address>
 452
 453 </body>
 454 </html>