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