blob: db1838d5c8811523679b17716923b0b9950b43db [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
Chris Lattner7911ce22004-05-23 21:07:27 +000028<div class="doc_author">
29 <p>Written by John Criswell</p>
30</div>
31
Misha Brukmanf6a04072004-05-12 20:57:43 +000032<!-- *********************************************************************** -->
33<div class="doc_section"><a name="overview">Overview</a></div>
34<!-- *********************************************************************** -->
John Criswellf2413ae2003-07-03 15:37:52 +000035
Misha Brukmanf6a04072004-05-12 20:57:43 +000036<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +000037
Misha Brukmanf6a04072004-05-12 20:57:43 +000038<p>The LLVM build system is designed to facilitate the building of third party
39projects that use LLVM header files, libraries, and tools. In order to use
40these facilities, a Makefile from a project must do the following things:</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000041
Misha Brukmanf6a04072004-05-12 20:57:43 +000042<ol>
Reid Spencer39865c02005-01-16 02:21:18 +000043 <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>
Misha Brukmanf6a04072004-05-12 20:57:43 +000057</ol>
John Criswell7a4b96d2003-10-16 19:53:53 +000058
Misha Brukmanf6a04072004-05-12 20:57:43 +000059<p>There are two ways that you can set all of these variables:</p>
Misha Brukmanf6a04072004-05-12 20:57:43 +000060<ol>
Reid Spencer39865c02005-01-16 02:21:18 +000061 <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>
Misha Brukmanf6a04072004-05-12 20:57:43 +000066</ol>
John Criswell7a4b96d2003-10-16 19:53:53 +000067
Reid Spencer39865c02005-01-16 02:21:18 +000068<p>This document assumes that you will base your project on the LLVM sample
Misha Brukmanf6a04072004-05-12 20:57:43 +000069project found in <tt>llvm/projects/sample</tt>. If you want to devise your own
70build system, studying the sample project and LLVM Makefiles will probably
71provide enough information on how to write your own Makefiles.</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000072
Misha Brukmanf6a04072004-05-12 20:57:43 +000073</div>
John Criswell7a4b96d2003-10-16 19:53:53 +000074
Misha Brukmanf6a04072004-05-12 20:57:43 +000075<!-- *********************************************************************** -->
76<div class="doc_section">
77 <a name="create">Create a Project from the Sample Project</a>
78</div>
79<!-- *********************************************************************** -->
John Criswell7a4b96d2003-10-16 19:53:53 +000080
Misha Brukmanf6a04072004-05-12 20:57:43 +000081<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +000082
Misha Brukmanf6a04072004-05-12 20:57:43 +000083<p>Follow these simple steps to start your project:</p>
John Criswell7a4b96d2003-10-16 19:53:53 +000084
Misha Brukmanf6a04072004-05-12 20:57:43 +000085<ol>
86<li>Copy the <tt>llvm/projects/sample</tt> directory to any place of your
87choosing. You can place it anywhere you like. Rename the directory to match
88the name of your project.</li>
John Criswell7a4b96d2003-10-16 19:53:53 +000089
Misha Brukmanf6a04072004-05-12 20:57:43 +000090<li>Add your source code and Makefiles to your source tree.</li>
John Criswell7a4b96d2003-10-16 19:53:53 +000091
Misha Brukmanf6a04072004-05-12 20:57:43 +000092<li>If you want your Makefiles to be configured by the <tt>configure</tt>
93script, or if you want to support multiple object directories, add your
94Makefiles 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
96copy a file, unmodified, from the source directory to the object directory.</li>
John Criswellf2413ae2003-07-03 15:37:52 +000097
Misha Brukmanf6a04072004-05-12 20:57:43 +000098<li>After updating <tt>autoconf/configure.ac</tt>, regenerate the
99configure script with these commands:
John Criswellf2413ae2003-07-03 15:37:52 +0000100
Misha Brukmanf6a04072004-05-12 20:57:43 +0000101<div class="doc_code">
102<p><tt>% cd autoconf<br>
103 % autoconf -o ../configure</tt></p>
104</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000105
Misha Brukmanf6a04072004-05-12 20:57:43 +0000106<p>You must be using Autoconf version 2.57 or higher.</p></li>
John Criswell7a4b96d2003-10-16 19:53:53 +0000107
Misha Brukmanf6a04072004-05-12 20:57:43 +0000108<li>Run <tt>configure</tt> in the directory in which you want to place
109object code. Use the following options to tell your project where it
110can find LLVM:
John Criswell7a4b96d2003-10-16 19:53:53 +0000111
Misha Brukmanf6a04072004-05-12 20:57:43 +0000112 <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>
John Criswell7a4b96d2003-10-16 19:53:53 +0000122
Misha Brukmanf6a04072004-05-12 20:57:43 +0000123<p>That's it! Now all you have to do is type <tt>gmake</tt> in the root of
124your object directory, and your project should build.</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000125
Misha Brukmanf6a04072004-05-12 20:57:43 +0000126</div>
John Criswell7a4b96d2003-10-16 19:53:53 +0000127
Misha Brukmanf6a04072004-05-12 20:57:43 +0000128<!-- *********************************************************************** -->
129<div class="doc_section">
130 <a name="source">Source Tree Layout</a>
131</div>
132<!-- *********************************************************************** -->
John Criswellf2413ae2003-07-03 15:37:52 +0000133
Misha Brukmanf6a04072004-05-12 20:57:43 +0000134<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +0000135
Misha Brukmanf6a04072004-05-12 20:57:43 +0000136<p>In order to use the LLVM build system, you will want to organize your
137source code so that it can benefit from the build system's features.
138Mainly, you want your source tree layout to look similar to the LLVM
139source tree layout. The best way to do this is to just copy the
140project tree from <tt>llvm/projects/sample</tt> and modify it to meet
141your needs, but you can certainly add to it if you want.</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000142
Misha Brukmanf6a04072004-05-12 20:57:43 +0000143<p>Underneath your top level directory, you should have the following
144directories:</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000145
Misha Brukmanf6a04072004-05-12 20:57:43 +0000146<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.
John Criswellf2413ae2003-07-03 15:37:52 +0000153
Misha Brukmanf6a04072004-05-12 20:57:43 +0000154 <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.
John Criswellf2413ae2003-07-03 15:37:52 +0000159
Misha Brukmanf6a04072004-05-12 20:57:43 +0000160 <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>.
John Criswellf2413ae2003-07-03 15:37:52 +0000170
Misha Brukmanf6a04072004-05-12 20:57:43 +0000171 <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>
John Criswellf2413ae2003-07-03 15:37:52 +0000178
Misha Brukmanf6a04072004-05-12 20:57:43 +0000179 <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>
Tanya Lattnerd10bc6e2004-12-08 17:25:46 +0000184 Currently, the LLVM build system provides basic support for tests.
185 The LLVM system provides the following:
Misha Brukmanf6a04072004-05-12 20:57:43 +0000186 <ul>
187 <li>
Tanya Lattnerd10bc6e2004-12-08 17:25:46 +0000188 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
Misha Brukmanf6a04072004-05-12 20:57:43 +0000196 <p>
John Criswell2b89a6a2003-10-21 19:35:06 +0000197
Misha Brukmanf6a04072004-05-12 20:57:43 +0000198 <li>
John Criswell9e2485c2004-12-10 15:51:16 +0000199 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
Misha Brukmanf6a04072004-05-12 20:57:43 +0000202 programs to test your code, gather statistics information, and
John Criswell9e2485c2004-12-10 15:51:16 +0000203 compare it to the current LLVM performance statistics.
Misha Brukmanf6a04072004-05-12 20:57:43 +0000204 <p>
205 Currently, there is no way to hook your tests directly into the
John Criswell9e2485c2004-12-10 15:51:16 +0000206 <tt>llvm/test</tt> testing harness. You will simply
Misha Brukmanf6a04072004-05-12 20:57:43 +0000207 need to find a way to use the source provided within that directory
208 on your own.
209 </ul>
210</dl>
John Criswell2b89a6a2003-10-21 19:35:06 +0000211
Misha Brukmanf6a04072004-05-12 20:57:43 +0000212<p>Typically, you will want to build your <b>lib</b> directory first followed by
213your <b>tools</b> directory.</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000214
Misha Brukmanf6a04072004-05-12 20:57:43 +0000215</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000216
Misha Brukmanf6a04072004-05-12 20:57:43 +0000217<!-- *********************************************************************** -->
218<div class="doc_section">
219 <a name="makefiles">Writing LLVM Style Makefiles</a>
220</div>
221<!-- *********************************************************************** -->
John Criswellf2413ae2003-07-03 15:37:52 +0000222
Misha Brukmanf6a04072004-05-12 20:57:43 +0000223<div class="doc_text">
John Criswellf2413ae2003-07-03 15:37:52 +0000224
Misha Brukmanf6a04072004-05-12 20:57:43 +0000225<p>The LLVM build system provides a convenient way to build libraries and
226executables. Most of your project Makefiles will only need to define a few
227variables. Below is a list of the variables one can set and what they can
228do:</p>
John Criswellf2413ae2003-07-03 15:37:52 +0000229
Misha Brukmanf6a04072004-05-12 20:57:43 +0000230</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000231
Misha Brukmanf6a04072004-05-12 20:57:43 +0000232<!-- ======================================================================= -->
233<div class="doc_subsection">
234 <a name="reqVars">Required Variables</a>
235</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000236
Misha Brukmanf6a04072004-05-12 20:57:43 +0000237<div class="doc_text">
John Criswellf2413ae2003-07-03 15:37:52 +0000238
Misha Brukmanf6a04072004-05-12 20:57:43 +0000239<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>
John Criswellf2413ae2003-07-03 15:37:52 +0000247
Misha Brukmanf6a04072004-05-12 20:57:43 +0000248</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000249
Misha Brukmanf6a04072004-05-12 20:57:43 +0000250<!-- ======================================================================= -->
251<div class="doc_subsection">
252 <a name="varsBuildDir">Variables for Building Subdirectories</a>
253</div>
John Criswellf2413ae2003-07-03 15:37:52 +0000254
Misha Brukmanf6a04072004-05-12 20:57:43 +0000255<div class="doc_text">
John Criswell37c154a2003-10-17 21:50:38 +0000256
Misha Brukmanf6a04072004-05-12 20:57:43 +0000257<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>
John Criswellf2413ae2003-07-03 15:37:52 +0000264
Misha Brukmanf6a04072004-05-12 20:57:43 +0000265 <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>
John Criswellf2413ae2003-07-03 15:37:52 +0000271
Misha Brukmanf6a04072004-05-12 20:57:43 +0000272 <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>
John Criswellf2413ae2003-07-03 15:37:52 +0000278
Misha Brukmanf6a04072004-05-12 20:57:43 +0000279</div>
John Criswell7a4b96d2003-10-16 19:53:53 +0000280
Misha Brukmanf6a04072004-05-12 20:57:43 +0000281<!-- ======================================================================= -->
282<div class="doc_subsection">
283 <a name="varsBuildLib">Variables for Building Libraries</a>
284</div>
John Criswell7a4b96d2003-10-16 19:53:53 +0000285
Misha Brukmanf6a04072004-05-12 20:57:43 +0000286<div class="doc_text">
John Criswell7a4b96d2003-10-16 19:53:53 +0000287
Misha Brukmanf6a04072004-05-12 20:57:43 +0000288<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>
John Criswell7a4b96d2003-10-16 19:53:53 +0000296
Misha Brukmanf6a04072004-05-12 20:57:43 +0000297 <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>
John Criswell7a4b96d2003-10-16 19:53:53 +0000303
Misha Brukmanf6a04072004-05-12 20:57:43 +0000304 <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
395whether 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
Reid Spencerd967c802005-01-16 02:38:06 +0000401 <tt>PROJ_OBJ_ROOT/&lt;type&gt;/lib</tt>, where type is <tt>Debug</tt>,
Misha Brukmanf6a04072004-05-12 20:57:43 +0000402 <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
Reid Spencerd967c802005-01-16 02:38:06 +0000407 <tt>PROJ_OBJ_ROOT/&lt;type&gt;/bin</tt>, where type is <tt>Debug</tt>,
Misha Brukmanf6a04072004-05-12 20:57:43 +0000408 <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,
423the LLVM team would be more than happy to help. You can always post your
424questions to the <a
425href="http://mail.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developers
426Mailing List</a>.</p>
427
428</div>
429
430<!-- *********************************************************************** -->
John Criswell7a4b96d2003-10-16 19:53:53 +0000431<hr>
Misha Brukmanf6a04072004-05-12 20:57:43 +0000432<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>
Misha Brukman733adcb2003-10-30 01:23:40 +0000443
John Criswellf2413ae2003-07-03 15:37:52 +0000444</body>
445</html>