blob: 6be0a892f5b72dd94a1de449fe51245cb90b3d16 [file] [log] [blame]
Misha Brukmanf6a04072004-05-12 20:57:43 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
John Criswellf2413ae2003-07-03 15:37:52 +00003<html>
Misha Brukmanf6a04072004-05-12 20:57:43 +00004<head>
5 <title>Creating an LLVM Project</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
John Criswellf2413ae2003-07-03 15:37:52 +00009
Misha Brukmanf6a04072004-05-12 20:57:43 +000010<div class="doc_title">Creating an LLVM Project</div>
John Criswellf2413ae2003-07-03 15:37:52 +000011
Misha Brukmanf6a04072004-05-12 20:57:43 +000012<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>
John Criswellf2413ae2003-07-03 15:37:52 +000027
Misha Brukmanf6a04072004-05-12 20:57:43 +000028<!-- *********************************************************************** -->
29<div class="doc_section"><a name="overview">Overview</a></div>
30<!-- *********************************************************************** -->
John Criswellf2413ae2003-07-03 15:37:52 +000031
Misha Brukmanf6a04072004-05-12 20:57:43 +000032<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +000033
Misha Brukmanf6a04072004-05-12 20:57:43 +000034<p>The LLVM build system is designed to facilitate the building of third party
35projects that use LLVM header files, libraries, and tools. In order to use
36these facilities, a Makefile from a project must do the following things:</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000037
Misha Brukmanf6a04072004-05-12 20:57:43 +000038<ol>
39<li>Set environment variables.There are several environment variables that a
40Makefile needs to set to use the LLVM build system:
John Criswell7a4b96d2003-10-16 19:53:53 +000041
Misha Brukmanf6a04072004-05-12 20:57:43 +000042<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>
John Criswell7a4b96d2003-10-16 19:53:53 +000057
Misha Brukmanf6a04072004-05-12 20:57:43 +000058<p>There are two ways that you can set all of these variables:</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000059
Misha Brukmanf6a04072004-05-12 20:57:43 +000060<ol>
61<li>You can write your own Makefiles which hard-code these values.</li>
John Criswell7a4b96d2003-10-16 19:53:53 +000062
Misha Brukmanf6a04072004-05-12 20:57:43 +000063<li> You can use the pre-made LLVM sample project. This sample project includes
64Makefiles, a configure script that can be used to configure the location of
65LLVM, and the ability to support multiple object directories from a single
66source directory.</li>
67</ol>
John Criswell7a4b96d2003-10-16 19:53:53 +000068
Misha Brukmanf6a04072004-05-12 20:57:43 +000069<p>This document assumes that you will base your project off of the LLVM sample
70project found in <tt>llvm/projects/sample</tt>. If you want to devise your own
71build system, studying the sample project and LLVM Makefiles will probably
72provide enough information on how to write your own Makefiles.</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000073
Misha Brukmanf6a04072004-05-12 20:57:43 +000074</div>
John Criswell7a4b96d2003-10-16 19:53:53 +000075
Misha Brukmanf6a04072004-05-12 20:57:43 +000076<!-- *********************************************************************** -->
77<div class="doc_section">
78 <a name="create">Create a Project from the Sample Project</a>
79</div>
80<!-- *********************************************************************** -->
John Criswell7a4b96d2003-10-16 19:53:53 +000081
Misha Brukmanf6a04072004-05-12 20:57:43 +000082<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +000083
Misha Brukmanf6a04072004-05-12 20:57:43 +000084<p>Follow these simple steps to start your project:</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000085
Misha Brukmanf6a04072004-05-12 20:57:43 +000086<ol>
87<li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
88choosing. You can place it anywhere you like. Rename the directory to match
89the name of your project.</li>
John Criswell7a4b96d2003-10-16 19:53:53 +000090
Misha Brukmanf6a04072004-05-12 20:57:43 +000091<li>Add your source code and Makefiles to your source tree.</li>
John Criswell7a4b96d2003-10-16 19:53:53 +000092
Misha Brukmanf6a04072004-05-12 20:57:43 +000093<li>If you want your Makefiles to be configured by the <tt>configure</tt>
94script, or if you want to support multiple object directories, add your
95Makefiles 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
97copy a file, unmodified, from the source directory to the object directory.</li>
John Criswellf2413ae2003-07-03 15:37:52 +000098
Misha Brukmanf6a04072004-05-12 20:57:43 +000099<li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
100configure script with these commands:
John Criswellf2413ae2003-07-03 15:37:52 +0000101
Misha Brukmanf6a04072004-05-12 20:57:43 +0000102<div class="doc_code">
103<p><tt>% cd autoconf<br>
104 % autoconf -o ../configure</tt></p>
105</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000106
Misha Brukmanf6a04072004-05-12 20:57:43 +0000107<p>You must be using Autoconf version 2.57 or higher.</p></li>
John Criswell7a4b96d2003-10-16 19:53:53 +0000108
Misha Brukmanf6a04072004-05-12 20:57:43 +0000109<li>Run <tt>configure</tt> in the directory in which you want to place
110object code. Use the following options to tell your project where it
111can find LLVM:
John Criswell7a4b96d2003-10-16 19:53:53 +0000112
Misha Brukmanf6a04072004-05-12 20:57:43 +0000113 <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>
John Criswell7a4b96d2003-10-16 19:53:53 +0000123
Misha Brukmanf6a04072004-05-12 20:57:43 +0000124<p>That's it! Now all you have to do is type <tt>gmake</tt> in the root of
125your object directory, and your project should build.</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000126
Misha Brukmanf6a04072004-05-12 20:57:43 +0000127</div>
John Criswell7a4b96d2003-10-16 19:53:53 +0000128
Misha Brukmanf6a04072004-05-12 20:57:43 +0000129<!-- *********************************************************************** -->
130<div class="doc_section">
131 <a name="source">Source Tree Layout</a>
132</div>
133<!-- *********************************************************************** -->
John Criswellf2413ae2003-07-03 15:37:52 +0000134
Misha Brukmanf6a04072004-05-12 20:57:43 +0000135<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +0000136
Misha Brukmanf6a04072004-05-12 20:57:43 +0000137<p>In order to use the LLVM build system, you will want to organize your
138source code so that it can benefit from the build system's features.
139Mainly, you want your source tree layout to look similar to the LLVM
140source tree layout. The best way to do this is to just copy the
141project tree from <tt>llvm/projects/sample</tt> and modify it to meet
142your needs, but you can certainly add to it if you want.</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000143
Misha Brukmanf6a04072004-05-12 20:57:43 +0000144<p>Underneath your top level directory, you should have the following
145directories:</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000146
Misha Brukmanf6a04072004-05-12 20:57:43 +0000147<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.
John Criswellf2413ae2003-07-03 15:37:52 +0000154
Misha Brukmanf6a04072004-05-12 20:57:43 +0000155 <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.
John Criswellf2413ae2003-07-03 15:37:52 +0000160
Misha Brukmanf6a04072004-05-12 20:57:43 +0000161 <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>.
John Criswellf2413ae2003-07-03 15:37:52 +0000171
Misha Brukmanf6a04072004-05-12 20:57:43 +0000172 <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>
John Criswellf2413ae2003-07-03 15:37:52 +0000179
Misha Brukmanf6a04072004-05-12 20:57:43 +0000180 <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>
John Criswell2b89a6a2003-10-21 19:35:06 +0000199
Misha Brukmanf6a04072004-05-12 20:57:43 +0000200 <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>
John Criswell2b89a6a2003-10-21 19:35:06 +0000213
Misha Brukmanf6a04072004-05-12 20:57:43 +0000214<p>Typically, you will want to build your <b>lib</b> directory first followed by
215your <b>tools</b> directory.</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000216
Misha Brukmanf6a04072004-05-12 20:57:43 +0000217</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000218
Misha Brukmanf6a04072004-05-12 20:57:43 +0000219<!-- *********************************************************************** -->
220<div class="doc_section">
221 <a name="makefiles">Writing LLVM Style Makefiles</a>
222</div>
223<!-- *********************************************************************** -->
John Criswellf2413ae2003-07-03 15:37:52 +0000224
Misha Brukmanf6a04072004-05-12 20:57:43 +0000225<div class="doc_text">
John Criswellf2413ae2003-07-03 15:37:52 +0000226
Misha Brukmanf6a04072004-05-12 20:57:43 +0000227<p>The LLVM build system provides a convenient way to build libraries and
228executables. Most of your project Makefiles will only need to define a few
229variables. Below is a list of the variables one can set and what they can
230do:</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000231
Misha Brukmanf6a04072004-05-12 20:57:43 +0000232</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000233
Misha Brukmanf6a04072004-05-12 20:57:43 +0000234<!-- ======================================================================= -->
235<div class="doc_subsection">
236 <a name="reqVars">Required Variables</a>
237</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000238
Misha Brukmanf6a04072004-05-12 20:57:43 +0000239<div class="doc_text">
John Criswellf2413ae2003-07-03 15:37:52 +0000240
Misha Brukmanf6a04072004-05-12 20:57:43 +0000241<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>
John Criswellf2413ae2003-07-03 15:37:52 +0000249
Misha Brukmanf6a04072004-05-12 20:57:43 +0000250</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000251
Misha Brukmanf6a04072004-05-12 20:57:43 +0000252<!-- ======================================================================= -->
253<div class="doc_subsection">
254 <a name="varsBuildDir">Variables for Building Subdirectories</a>
255</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000256
Misha Brukmanf6a04072004-05-12 20:57:43 +0000257<div class="doc_text">
John Criswell37c154a2003-10-17 21:50:38 +0000258
Misha Brukmanf6a04072004-05-12 20:57:43 +0000259<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>
John Criswellf2413ae2003-07-03 15:37:52 +0000266
Misha Brukmanf6a04072004-05-12 20:57:43 +0000267 <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>
John Criswellf2413ae2003-07-03 15:37:52 +0000273
Misha Brukmanf6a04072004-05-12 20:57:43 +0000274 <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>
John Criswellf2413ae2003-07-03 15:37:52 +0000280
Misha Brukmanf6a04072004-05-12 20:57:43 +0000281</div>
John Criswell7a4b96d2003-10-16 19:53:53 +0000282
Misha Brukmanf6a04072004-05-12 20:57:43 +0000283<!-- ======================================================================= -->
284<div class="doc_subsection">
285 <a name="varsBuildLib">Variables for Building Libraries</a>
286</div>
John Criswell7a4b96d2003-10-16 19:53:53 +0000287
Misha Brukmanf6a04072004-05-12 20:57:43 +0000288<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +0000289
Misha Brukmanf6a04072004-05-12 20:57:43 +0000290<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>
John Criswell7a4b96d2003-10-16 19:53:53 +0000298
Misha Brukmanf6a04072004-05-12 20:57:43 +0000299 <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>
John Criswell7a4b96d2003-10-16 19:53:53 +0000305
Misha Brukmanf6a04072004-05-12 20:57:43 +0000306 <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
397whether 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,
425the LLVM team would be more than happy to help. You can always post your
426questions to the <a
427href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
428Mailing List</a>.</p>
429
430</div>
431
432<!-- *********************************************************************** -->
John Criswell7a4b96d2003-10-16 19:53:53 +0000433<hr>
Misha Brukmanf6a04072004-05-12 20:57:43 +0000434<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>
Misha Brukman733adcb2003-10-30 01:23:40 +0000445
John Criswellf2413ae2003-07-03 15:37:52 +0000446</body>
447</html>