Removed the -only-static option as it is no longer required (and didn't work
[oota-llvm.git] / docs / Projects.html
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>