Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 8a0b9242196e6cd97dafecc0bd26d7d72170b326 / . / docs / FAQ.html
blob: 8f9a9a7b69715537f52330c766b309bc36f52f50 [file] [log] [blame]
Misha Brukmana6538852003-11-06 21:55:44 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>LLVM: Frequently Asked Questions</title>
6 <style>
7 @import url("llvm.css");
8 .question { font-weight: bold }
9 .answer { margin-left: 2em }
10 </style>
11</head>
12<body>
John Criswellc310f622003-10-13 16:13:06 +0000[diff] [blame]13
Misha Brukmana6538852003-11-06 21:55:44 +0000[diff] [blame]14<div class="doc_title">
15 LLVM: Frequently Asked Questions
16</div>
17
18<ol>
19 <li><a href="#license">License</a>
20 <ol>
21 <li>Why are the LLVM source code and the front-end distributed under different
22 licenses?</li>
23 <li>Does the University of Illinois Open Source License really qualify as an
24 "open source" license?</li>
25 <li>Can I modify LLVM source code and redistribute the modified source?</li>
26 <li>Can I modify LLVM source code and redistribute binaries or other tools
27 based on it, without redistributing the source?</li>
28 </ol></li>
29
30 <li><a href="#source">Source code</a>
31 <ol>
32 <li>In what language is LLVM written?</li>
33 <li>How portable is the LLVM source code?</li>
34 </ol></li>
35
36 <li><a href="#build">Build Problems</a>
37 <ol>
38 <li>When I run configure, it finds the wrong C compiler.</li>
39 <li>I compile the code, and I get some error about <tt>/localhome</tt>.</li>
40 <li>The <tt>configure</tt> script finds the right C compiler, but it uses the
41 LLVM linker from a previous build. What do I do?</li>
42 <li>When creating a dynamic library, I get a strange GLIBC error.</li>
43 <li>I've updated my source tree from CVS, and now my build is trying to use a
44 file/directory that doesn't exist.</li>
45 <li>I've modified a Makefile in my source tree, but my build tree keeps using
46 the old version. What do I do?</li>
47 <li>I've upgraded to a new version of LLVM, and I get strange build
48 errors.</li>
49 <li>I've built LLVM and am testing it, but the tests freeze.</li>
50 <li>Why do test results differ when I perform different types of builds?</li>
Chris Lattner8a0b9242003-12-08 05:43:19 +0000[diff] [blame^]51 <li>Compiling LLVM with GCC 3.3 on SuSE 9 fails, what should I do?</li>
Misha Brukmana6538852003-11-06 21:55:44 +0000[diff] [blame]52 </ol></li>
John Criswell76c1e382003-11-18 16:08:49 +0000[diff] [blame]53
Chris Lattnercc33d702003-11-19 05:53:12 +0000[diff] [blame]54 <li><a href="#cfe">Using the GCC Front End</a>
John Criswell76c1e382003-11-18 16:08:49 +0000[diff] [blame]55 <ol>
56 <li>
57 When I compile software that uses a configure script, the configure script
58 thinks my system has all of the header files and libraries it is testing
59 for. How do I get configure to work correctly?
60 </li>
61
62 <li>
63 When I compile code using the LLVM GCC front end, it complains that it
64 cannot find crtend.o.
65 </li>
66 </ol>
67 </li>
Chris Lattnercc33d702003-11-19 05:53:12 +0000[diff] [blame]68
69 <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
70 <ol>
71 <li>What is this <tt>__main()</tt> call that gets inserted into
72 <tt>main()</tt>?</li>
73 </ol>
74 </li>
Misha Brukmana6538852003-11-06 21:55:44 +0000[diff] [blame]75</ol>
76
77<!-- *********************************************************************** -->
78<div class="doc_section">
79 <a name="license">License</a>
80</div>
81<!-- *********************************************************************** -->
82
83<div class="question">
84<p>Why are the LLVM source code and the front-end distributed under different
85licenses?</p>
86</div>
87
88<div class="answer">
89<p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
90Our aim is to distribute LLVM source code under a <em>much less restrictive</em>
91license, in particular one that does not compel users who distribute tools based
92on modifying the source to redistribute the modified source code as well.</p>
93</div>
94
95<div class="question">
96<p>Does the University of Illinois Open Source License really qualify as an
97"open source" license?</p>
98</div>
99
100<div class="answer">
101<p>Yes, the license is <a
102href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open
103Source Initiative (OSI).</p>
104</div>
105
106<div class="question">
107<p>Can I modify LLVM source code and redistribute the modified source?</p>
108</div>
109
110<div class="answer">
111<p>Yes. The modified source distribution must retain the copyright notice and
112follow the three bulletted conditions listed in the <a
113href="http://llvm.cs.uiuc.edu/releases/1.0/LICENSE.TXT">LLVM license</a>.</p>
114</div>
115
116<div class="question">
117<p>Can I modify LLVM source code and redistribute binaries or other tools based
118on it, without redistributing the source?</p>
119</div>
120
121<div class="answer">
122<p>Yes, this is why we distribute LLVM under a less restrictive license than
123GPL, as explained in the first question above.</p>
124</div>
125
126<!-- *********************************************************************** -->
127<div class="doc_section">
128 <a name="source">Source Code</a>
129</div>
130<!-- *********************************************************************** -->
131
132<div class="question">
133<p>In what language is LLVM written?</p>
134</div>
135
136<div class="answer">
137<p>All of the LLVM tools and libraries are written in C++ with extensive use of
138the STL.</p>
139</div>
140
141<div class="question">
142<p>How portable is the LLVM source code?</p>
143</div>
144
145<div class="answer">
146<p>The LLVM source code should be portable to most modern UNIX-like operating
147systems. Most of the code is written in standard C++ with operating system
148services abstracted to a support library. The tools required to build and test
149LLVM have been ported to a plethora of platforms.</p>
150
151<p>Some porting problems may exist in the following areas:</p>
152
153<ul>
154
155 <li>The GCC front end code is not as portable as the LLVM suite, so it may not
156 compile as well on unsupported platforms.</li>
157
158 <li>The Python test classes are more UNIX-centric than they should be, so
159 porting to non-UNIX like platforms (i.e. Windows, MacOS 9) will require some
160 effort.</li>
161
162 <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
163 Shell and sed. Porting to systems without these tools (MacOS 9, Plan 9) will
164 require more effort.</li>
165
166</ul>
167
168</div>
169
170<!-- *********************************************************************** -->
171<div class="doc_section">
172 <a name="build">Build Problems</a>
173</div>
174<!-- *********************************************************************** -->
175
176<div class="question">
177<p>When I run configure, it finds the wrong C compiler.</p>
178</div>
179
180<div class="answer">
181
182<p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
183<tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt> and <tt>CXX</tt>
184for the C and C++ compiler, respectively.</p>
185
186<p>If <tt>configure</tt> finds the wrong compiler, either adjust your
187<tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
188explicitly.</p>
189
190</div>
191
192<div class="question">
193<p>I compile the code, and I get some error about <tt>/localhome</tt>.</p>
194</div>
195
196<div class="answer">
197
198<p>There are several possible causes for this. The first is that you didn't set
199a pathname properly when using <tt>configure</tt>, and it defaulted to a
200pathname that we use on our research machines.</p>
201
202<p>Another possibility is that we hardcoded a path in our Makefiles. If you see
203this, please email the LLVM bug mailing list with the name of the offending
204Makefile and a description of what is wrong with it.</p>
205
206</div>
207
208<div class="question">
209<p>The <tt>configure</tt> script finds the right C compiler, but it uses the
210LLVM linker from a previous build. What do I do?</p>
211</div>
212
213<div class="answer">
214<p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
215if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
216it:</p>
217
218<ol>
219
220 <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
221 program appears first in the <tt>PATH</tt>. This may work, but may not be
222 convenient when you want them <i>first</i> in your path for other
223 work.</p></li>
224
225 <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
226 correct. In a Borne compatible shell, the syntax would be:</p>
227
228 <p><tt>PATH=<the path without the bad program> ./configure ...</tt></p>
229
230 <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
231 to do its work without having to adjust your <tt>PATH</tt>
232 permanently.</p></li>
233
234</ol>
235
236</div>
237
238<div class="question">
239<p>When creating a dynamic library, I get a strange GLIBC error.</p>
240</div>
241
242<div class="answer">
243<p>Under some operating systems (i.e. Linux), libtool does not work correctly if
244GCC was compiled with the --disable-shared option. To work around this, install
245your own version of GCC that has shared libraries enabled by default.</p>
246</div>
247
248<div class="question">
249<p>I've updated my source tree from CVS, and now my build is trying to use a
250file/directory that doesn't exist.</p>
251</div>
252
253<div class="answer">
254<p>You need to re-run configure in your object directory. When new Makefiles
255are added to the source tree, they have to be copied over to the object tree in
256order to be used by the build.</p>
257</div>
258
259<div class="question">
260<p>I've modified a Makefile in my source tree, but my build tree keeps using the
261old version. What do I do?</p>
262</div>
263
264<div class="answer">
265
266<p>If the Makefile already exists in your object tree, you
267can just run the following command in the top level directory of your object
268tree:</p>
269
270<p><tt>./config.status &lt;relative path to Makefile&gt;</tt><p>
271
272<p>If the Makefile is new, you will have to modify the configure script to copy
273it over.</p>
274
275</div>
276
277<div class="question">
278<p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
279</div>
280
281<div class="answer">
282
283<p>Sometimes, changes to the LLVM source code alters how the build system works.
284Changes in libtool, autoconf, or header file dependencies are especially prone
285to this sort of problem.</p>
286
287<p>The best thing to try is to remove the old files and re-build. In most
288cases, this takes care of the problem. To do this, just type <tt>make
289clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
290
291</div>
292
293<div class="question">
294<p>I've built LLVM and am testing it, but the tests freeze.</p>
295</div>
296
297<div class="answer">
298
299<p>This is most likely occurring because you built a profile or release
300(optimized) build of LLVM and have not specified the same information on the
301<tt>gmake</tt> command line.</p>
302
303<p>For example, if you built LLVM with the command:</p>
304
305<p><tt>gmake ENABLE_PROFILING=1</tt>
306
307<p>...then you must run the tests with the following commands:</p>
308
309<p><tt>cd llvm/test<br>gmake ENABLE_PROFILING=1</tt></p>
310
311</div>
312
313<div class="question">
314<p>Why do test results differ when I perform different types of builds?</p>
315</div>
316
317<div class="answer">
318
319<p>The LLVM test suite is dependent upon several features of the LLVM tools and
320libraries.</p>
321
322<p>First, the debugging assertions in code are not enabled in optimized or
323profiling builds. Hence, tests that used to fail may pass.</p>
324
325<p>Second, some tests may rely upon debugging options or behavior that is only
326available in the debug build. These tests will fail in an optimized or profile
327build.</p>
328
329</div>
330
Chris Lattner8a0b9242003-12-08 05:43:19 +0000[diff] [blame^]331<div class="question">
332<p>Compiling LLVM with GCC 3.3 on SuSE 9 fails, what should I do?</p>
333</div>
334
335<div class="answer">
336<p>This is a bug in the customized version of GCC shipped with SuSE, and effects
337 projects other than LLVM. Complain loudly to SuSE. :)</p>
338</div>
339
Misha Brukmana6538852003-11-06 21:55:44 +0000[diff] [blame]340<!-- *********************************************************************** -->
John Criswell6ea30b02003-11-18 16:05:23 +0000[diff] [blame]341<div class="doc_section">
Chris Lattnercc33d702003-11-19 05:53:12 +0000[diff] [blame]342 <a name="cfe">Using the GCC Front End</a>
John Criswell6ea30b02003-11-18 16:05:23 +0000[diff] [blame]343</div>
344
345<div class="question">
346<p>
347When I compile software that uses a configure script, the configure script
348thinks my system has all of the header files and libraries it is testing for.
349How do I get configure to work correctly?
350</p>
351</div>
352
353<div class="answer">
354<p>
355The configure script is getting things wrong because the LLVM linker allows
356symbols to be undefined at link time (so that they can be resolved during JIT
357or translation to the C back end). That is why configure thinks your system
358"has everything."
359</p>
360<p>
361To work around this, perform the following steps:
362</p>
363
364<ol>
365 <li>
366 Make sure the CC and CXX environment variables contains the full path to the
367 LLVM GCC front end.
368 </li>
369
370 <li>
371 Make sure that the regular C compiler is first in your PATH.
372 </li>
373
374 <li>
375 Add the string "-Wl,-native" to your CFLAGS environment variable.
376 </li>
377</ol>
378
379<p>
380This will allow the gccld linker to create a native code executable instead of
381a shell script that runs the JIT. Creating native code requires standard
382linkage, which in turn will allow the configure script to find out if code is
383not linking on your system because the feature isn't available on your system.
384</p>
385</div>
386
Chris Lattnercc33d702003-11-19 05:53:12 +0000[diff] [blame]387<div class="question">
John Criswell6ea30b02003-11-18 16:05:23 +0000[diff] [blame]388<p>
389When I compile code using the LLVM GCC front end, it complains that it cannot
390find crtend.o.
391</p>
392</div>
393
Chris Lattnercc33d702003-11-19 05:53:12 +0000[diff] [blame]394<div class="answer">
John Criswell6ea30b02003-11-18 16:05:23 +0000[diff] [blame]395<p>
396In order to find crtend.o, you must have the directory in which it lives in
397your LLVM_LIB_SEARCH_PATH environment variable. For the binary distribution of
398the LLVM GCC front end, this will be the full path of the bytecode-libs
399directory inside of the LLVM GCC distribution.
400</p>
401</div>
Chris Lattnercc33d702003-11-19 05:53:12 +0000[diff] [blame]402
403
404<!-- *********************************************************************** -->
405<div class="doc_section">
406 <a name="cfe_code">Questions about code generated by the GCC front-end</a>
407</div>
408
409<div class="question">
410<p>
411What is this <tt>__main()</tt> call that gets inserted into <tt>main()</tt>?
412</p>
413</div>
414
415<div class="answer">
416<p>
417The <tt>__main</tt> call is inserted by the C/C++ compiler in order to guarantee
418that static constructors and destructors are called when the program starts up
419and shuts down. In C, you can create static constructors and destructors by
420using GCC extensions, and in C++ you can do so by creating a global variable
421whose class has a ctor or dtor.
422</p>
423
424<p>
425The actual implementation of <tt>__main</tt> lives in the
426<tt>llvm/runtime/GCCLibraries/crtend/</tt> directory in the source-base, and is
427linked in automatically when you link the program.
428</p>
429
430</div>
431
432
433
John Criswell6ea30b02003-11-18 16:05:23 +0000[diff] [blame]434<!-- *********************************************************************** -->
435<!-- *********************************************************************** -->
John Criswellc310f622003-10-13 16:13:06 +0000[diff] [blame]436
437<hr>
Misha Brukmana6538852003-11-06 21:55:44 +0000[diff] [blame]438<div class="doc_footer">
439 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
440 <br>
441 Last modified: $Date$
442</div>
John Criswellf08c5d82003-10-24 22:48:20 +0000[diff] [blame]443
John Criswellc310f622003-10-13 16:13:06 +0000[diff] [blame]444</body>
445</html>