Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / 56e4fa45654cd4a972298272750e1c032993e9ac / . / docs / Projects.html
blob: 2debb6f7be1bec0fd827e948d248a7bf6c6202cd [file] [log] [blame]
John Criswellf2413ae2003-07-03 15:37:52 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3 <head>
4 <title>Creating an LLVM Project</title>
5 </head>
6
7 <body bgcolor=white>
8
9 <center><h1>Creating an LLVM Project<br></h1></center>
10
11 <!--===============================================================-->
12 <h2><a name="a">Overview</a><hr></h2>
13 <!--===============================================================-->
14
15 In order to set up a new project that uses the LLVM build system,
16 libraries, and header files, follow these steps:
17
18 <ol>
19 <li>
20 Copy the <tt>llvm/projects/sample</tt> directory to any place
21 of your choosing. You can place it anywhere you like, although
22 someplace underneath your home directory would work best.
23 <p>
24
25 <li>
26 Edit the <tt>Makefile.config</tt> and <tt>Makefile.common</tt>
27 files so that the LLVM_SRC_ROOT variable equals the absolute
28 pathname of the LLVM source tree and LLVM_OBJ_ROOT equals the
29 pathname of where LLVM was built.
30
31 <p>
32
33 For example, if the LLVM source tree is in
34 <tt>/usr/home/joe/src/llvm</tt>, and you configured it with
35 <tt>--with-objroot=/tmp</tt> when his home directory is
36 <tt>/usr/home/joe</tt>, then
37 LLVM_SRC_ROOT=<tt>/usr/home/joe/src/llvm</tt> and
38 LLVM_OBJ_ROOT=<tt>/tmp/src/llvm</tt>.
39 <p>
40
41 <li>
42 Add your source code to the source tree.
43 <p>
44
45 <li>
46 Modify the various Makefiles to contain the names of the
47 objects that you want to build.
48 </ol>
49
50 <!--===============================================================-->
51 <h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
52 <!--===============================================================-->
53
54 In order to use the LLVM build system, you will want to lay out your
55 source code so that it can benefit from the build system's features.
56 Mainly, you want your source tree layout to look similar to the LLVM
57 source tree layout. The best way to do this is to just copy the
58 project tree from <tt>llvm/projects/sample</tt> and modify it to meet
59 your needs, but you can certainly add to it if you want.
60
61 Underneath your top level directory, you should have the following
62 directories:
63
64 <dl compact>
65 <dt><b>lib</b>
66 <dd>
67 This subdirectory should contain all of your library source
68 code. For each library that you build, you will have one
69 directory in <b>lib</b> that will contain that library's source
70 code.
71
72 <p>
73 Libraries can be object files, archives, or dynamic libraries.
74 The <b>lib</b> directory is just a good place for these as it
75 places them all in a directory from which they can be linked
76 later on.
77
78 <dt><b>include</b>
79 <dd>
80 This subdirectory should contain any header files that are
81 global to your project. By global, we mean that they are used
82 by more than one library or executable of your project.
83 <p>
84 By placing your header files in <b>include</b>, they will be
85 found automatically by the LLVM build system. For example, if
86 you have a file <b>include/jazz/note.h</b>, then your source
87 files can include it simply with <b>#include "jazz/note.h"</b>.
88
89 <dt><b>tools</b>
90 <dd>
91 This subdirectory should contain all of your source
92 code for executables. For each program that you build, you
93 will have one directory in <b>tools</b> that will contain that
94 program's source code.
95 </dl>
96
97 Typically, you will want to build your <b>lib</b> directory first
98 followed by your <b>tools</b> directory.
99
100 <!--===============================================================-->
101 <h2><a name="Makefile Variables">Makefile Variables</a><hr></h2>
102 <!--===============================================================-->
103 The LLVM build system provides several variables which you may
104 use.
105
106 <h3> Required Variables </h3>
107 <dl compact>
108 <dt>LEVEL
109 <dd>
110 This variable is the relative path from this Makefile to the
111 top directory of your project's source code. For example, if
112 your source code is in /tmp/src, then the Makefile in
113 /tmp/src/jump/high would set LEVEL to "../..".
114 </dl>
115
116 <h3> Variables for Building Subdirectories</h3>
117 <dl compact>
118 <dt>DIRS
119 <dd>
120 This is a space separated list of subdirectories that should be
121 built. They will be built, one at a time, in the order
122 specified.
123 <p>
124
125 <dt>PARALLEL_DIRS
126 <dd>
127 This is a list of directories that can be built in parallel.
128 These will be built after the directories in DIRS have been
129 built.
130 <p>
131
132 <dt>OPTIONAL_DIRS
133 <dd>
134 This is a list of directories that can be built if they exist,
135 but will not cause an error if they do not exist. They are
136 built serially in the order in which they are listed.
137 </dl>
138
139 <h3> Variables for Building Libraries</h3>
140 <dl compact>
141 <dt>LIBRARYNAME
142 <dd>
143 This variable contains the base name of the library that will
144 be built. For example, to build a library named
145 <tt>libsample.a</tt>, LIBRARYNAME should be set to
146 <tt>sample</tt>.
147 <p>
148
149 <dt>BUILD_ARCHIVE
150 <dd>
151 By default, a library is a <tt>.o</tt> file that is linked
152 directly into a program. However, if you set the BUILD_ARCHIVE
153 variable, an archive library (sometimes known as a static
154 library) will be built instead.
155 <p>
156
157 <dt>SHARED_LIBRARY
158 <dd>
159 If SHARED_LIBRARY is defined in your Makefile, then the
160 Makefiles will generate a shared (or dynamic) library.
161 </dl>
162
163 <h3> Variables for Building Programs</h3>
164 <dl compact>
165 <dt>TOOLNAME
166 <dd>
167 This variable contains the name of the program that will
168 be built. For example, to build an executable named
169 <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
170 <p>
171
172 <dt>USEDLIBS
173 <dd>
174 This variable holds a space separated list of libraries that
175 should be linked into the program. These libraries must either
176 be LLVM libraries or libraries that come from your <b>lib</b>
177 directory. The libraries must be specified by their base name.
178 For example, to link libsample.a, you would set USEDLIBS to
179 <tt>sample</tt>.
180 <p>
181 </dl>
182
183 <h3> Miscellaneous Variables</h3>
184 <dl compact>
185 <dt>ExtraSource
186 <dd>
187 This variable contains a space separated list of extra source
188 files that needs to be built. It is useful for including the
189 output of Lex and Yacc programs.
190 <p>
191
192 <dt>CFLAGS
193 <dt>CPPFLAGS
194 <dd>
195 This variable can be used to add options to the C and C++
196 compiler, respectively. It is typically used to add options
197 that tell the compiler the location of additional directories
198 to search for header files.
199 <p>
200 It is highly suggested that you append to these variable as
201 opposed to overwriting them. The master Makefiles may already
202 have useful options in them that you may not want to overwrite.
203 <p>
204 </dl>
205
206 <!--===============================================================-->
207 <h2><a name="Caveats">Caveats</a><hr></h2>
208 <!--===============================================================-->
209
210 Some caveats and known issues:
211 <ol>
212 <li>
213 The projects system currently uses the $HOME environment
214 variable in determining where object files should go. If $HOME
215 is not set, then your path relative to the root directory may
216 be used to determine where your object files go. It is
217 therefore advised that your source directory reside underneath
218 your home directory.
219 </ol>
220</body>
221</html>