Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / llvm / c7b6ce4af8e2c16e2f4287eedea25c426ac844a2 / . / docs / Projects.html
blob: b3b22b6738049836cd5e02fcd7b2e29a562a66cc [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
John Criswellc7b6ce42003-10-15 16:52:57 +0000[diff] [blame^]34 <tt>/usr/home/joe/src/llvm</tt>, and you built LLVM in
35 /tmp/llvmobj</tt>, then
John Criswellf2413ae2003-07-03 15:37:52 +0000[diff] [blame]36 LLVM_SRC_ROOT=<tt>/usr/home/joe/src/llvm</tt> and
John Criswellc7b6ce42003-10-15 16:52:57 +0000[diff] [blame^]37 LLVM_OBJ_ROOT=<tt>/tmp/llvmobj</tt>.
John Criswellf2413ae2003-07-03 15:37:52 +0000[diff] [blame]38 <p>
39
40 <li>
John Criswellc7b6ce42003-10-15 16:52:57 +0000[diff] [blame^]41 Add your source code to your source tree.
John Criswellf2413ae2003-07-03 15:37:52 +0000[diff] [blame]42 <p>
43
44 <li>
45 Modify the various Makefiles to contain the names of the
46 objects that you want to build.
47 </ol>
48
49 <!--===============================================================-->
50 <h2><a name="Source Tree Layout">Source Tree Layout</a><hr></h2>
51 <!--===============================================================-->
52
53 In order to use the LLVM build system, you will want to lay out your
54 source code so that it can benefit from the build system's features.
55 Mainly, you want your source tree layout to look similar to the LLVM
56 source tree layout. The best way to do this is to just copy the
57 project tree from <tt>llvm/projects/sample</tt> and modify it to meet
58 your needs, but you can certainly add to it if you want.
59
60 Underneath your top level directory, you should have the following
61 directories:
62
63 <dl compact>
64 <dt><b>lib</b>
65 <dd>
66 This subdirectory should contain all of your library source
67 code. For each library that you build, you will have one
68 directory in <b>lib</b> that will contain that library's source
69 code.
70
71 <p>
72 Libraries can be object files, archives, or dynamic libraries.
73 The <b>lib</b> directory is just a good place for these as it
74 places them all in a directory from which they can be linked
John Criswellc7b6ce42003-10-15 16:52:57 +0000[diff] [blame^]75 later.
John Criswellf2413ae2003-07-03 15:37:52 +0000[diff] [blame]76
77 <dt><b>include</b>
78 <dd>
79 This subdirectory should contain any header files that are
80 global to your project. By global, we mean that they are used
81 by more than one library or executable of your project.
82 <p>
83 By placing your header files in <b>include</b>, they will be
84 found automatically by the LLVM build system. For example, if
85 you have a file <b>include/jazz/note.h</b>, then your source
86 files can include it simply with <b>#include "jazz/note.h"</b>.
87
88 <dt><b>tools</b>
89 <dd>
90 This subdirectory should contain all of your source
91 code for executables. For each program that you build, you
92 will have one directory in <b>tools</b> that will contain that
93 program's source code.
94 </dl>
95
96 Typically, you will want to build your <b>lib</b> directory first
97 followed by your <b>tools</b> directory.
98
99 <!--===============================================================-->
100 <h2><a name="Makefile Variables">Makefile Variables</a><hr></h2>
101 <!--===============================================================-->
102 The LLVM build system provides several variables which you may
103 use.
104
105 <h3> Required Variables </h3>
106 <dl compact>
107 <dt>LEVEL
108 <dd>
109 This variable is the relative path from this Makefile to the
110 top directory of your project's source code. For example, if
111 your source code is in /tmp/src, then the Makefile in
112 /tmp/src/jump/high would set LEVEL to "../..".
113 </dl>
114
115 <h3> Variables for Building Subdirectories</h3>
116 <dl compact>
117 <dt>DIRS
118 <dd>
119 This is a space separated list of subdirectories that should be
120 built. They will be built, one at a time, in the order
121 specified.
122 <p>
123
124 <dt>PARALLEL_DIRS
125 <dd>
126 This is a list of directories that can be built in parallel.
127 These will be built after the directories in DIRS have been
128 built.
129 <p>
130
131 <dt>OPTIONAL_DIRS
132 <dd>
133 This is a list of directories that can be built if they exist,
134 but will not cause an error if they do not exist. They are
135 built serially in the order in which they are listed.
136 </dl>
137
138 <h3> Variables for Building Libraries</h3>
139 <dl compact>
140 <dt>LIBRARYNAME
141 <dd>
142 This variable contains the base name of the library that will
143 be built. For example, to build a library named
144 <tt>libsample.a</tt>, LIBRARYNAME should be set to
145 <tt>sample</tt>.
146 <p>
147
148 <dt>BUILD_ARCHIVE
149 <dd>
150 By default, a library is a <tt>.o</tt> file that is linked
151 directly into a program. However, if you set the BUILD_ARCHIVE
152 variable, an archive library (sometimes known as a static
153 library) will be built instead.
154 <p>
155
156 <dt>SHARED_LIBRARY
157 <dd>
158 If SHARED_LIBRARY is defined in your Makefile, then the
159 Makefiles will generate a shared (or dynamic) library.
160 </dl>
161
162 <h3> Variables for Building Programs</h3>
163 <dl compact>
164 <dt>TOOLNAME
165 <dd>
166 This variable contains the name of the program that will
167 be built. For example, to build an executable named
168 <tt>sample</tt>, TOOLNAME should be set to <tt>sample</tt>.
169 <p>
170
171 <dt>USEDLIBS
172 <dd>
173 This variable holds a space separated list of libraries that
174 should be linked into the program. These libraries must either
175 be LLVM libraries or libraries that come from your <b>lib</b>
176 directory. The libraries must be specified by their base name.
177 For example, to link libsample.a, you would set USEDLIBS to
178 <tt>sample</tt>.
179 <p>
180 </dl>
181
182 <h3> Miscellaneous Variables</h3>
183 <dl compact>
184 <dt>ExtraSource
185 <dd>
186 This variable contains a space separated list of extra source
187 files that needs to be built. It is useful for including the
188 output of Lex and Yacc programs.
189 <p>
190
191 <dt>CFLAGS
192 <dt>CPPFLAGS
193 <dd>
194 This variable can be used to add options to the C and C++
195 compiler, respectively. It is typically used to add options
196 that tell the compiler the location of additional directories
197 to search for header files.
198 <p>
199 It is highly suggested that you append to these variable as
200 opposed to overwriting them. The master Makefiles may already
201 have useful options in them that you may not want to overwrite.
202 <p>
203 </dl>
204
John Criswellf2413ae2003-07-03 15:37:52 +0000[diff] [blame]205</body>
206</html>