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