1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6 <title>LLVM: Frequently Asked Questions</title>
7 <style type="text/css">
8 @import url("_static/llvm.css");
9 .question { font-weight: bold }
10 .answer { margin-left: 2em }
16 LLVM: Frequently Asked Questions
20 <li><a href="#license">License</a>
22 <li>Does the University of Illinois Open Source License really qualify as an
23 "open source" license?</li>
25 <li>Can I modify LLVM source code and redistribute the modified source?</li>
27 <li>Can I modify LLVM source code and redistribute binaries or other tools
28 based on it, without redistributing the source?</li>
31 <li><a href="#source">Source code</a>
33 <li>In what language is LLVM written?</li>
35 <li>How portable is the LLVM source code?</li>
38 <li><a href="#build">Build Problems</a>
40 <li>When I run configure, it finds the wrong C compiler.</li>
42 <li>The <tt>configure</tt> script finds the right C compiler, but it uses
43 the LLVM linker from a previous build. What do I do?</li>
45 <li>When creating a dynamic library, I get a strange GLIBC error.</li>
47 <li>I've updated my source tree from Subversion, and now my build is trying
48 to use a file/directory that doesn't exist.</li>
50 <li>I've modified a Makefile in my source tree, but my build tree keeps
51 using the old version. What do I do?</li>
53 <li>I've upgraded to a new version of LLVM, and I get strange build
56 <li>I've built LLVM and am testing it, but the tests freeze.</li>
58 <li>Why do test results differ when I perform different types of
61 <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
63 <li>Compiling LLVM with GCC succeeds, but the resulting tools do not work,
64 what can be wrong?</li>
66 <li>When I use the test suite, all of the C Backend tests fail. What is
69 <li>After Subversion update, rebuilding gives the error "No rule to make
74 <li><a href="#felangs">Source Languages</a>
76 <li><a href="#langs">What source languages are supported?</a></li>
78 <li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
79 should I interface with the LLVM middle-end optimizers and back-end code
82 <li><a href="#langhlsupp">What support is there for higher level source
83 language constructs for building a compiler?</a></li>
85 <li><a href="GetElementPtr.html">I don't understand the GetElementPtr
86 instruction. Help!</a></li>
89 <li><a href="#cfe">Using the C and C++ Front Ends</a>
91 <li><a href="#platformindependent">Can I compile C or C++ code to
92 platform-independent LLVM bitcode?</a></li>
96 <li><a href="#cfe_code">Questions about code generated by the demo page</a>
98 <li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
99 <tt>_GLOBAL__I_a...</tt> stuff that happens when I
100 #include <iostream>?</a></li>
102 <li><a href="#codedce">Where did all of my code go??</a></li>
104 <li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in
107 <li><a href="#callconvwrong">Why does instcombine + simplifycfg turn
108 a call to a function with a mismatched calling convention into "unreachable"?
109 Why not make the verifier reject it?</a></li>
114 <div class="doc_author">
115 <p>Written by <a href="http://llvm.org/">The LLVM Team</a></p>
119 <!-- *********************************************************************** -->
121 <a name="license">License</a>
123 <!-- *********************************************************************** -->
127 <div class="question">
128 <p>Does the University of Illinois Open Source License really qualify as an
129 "open source" license?</p>
134 is <a href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by
135 the Open Source Initiative (OSI).</p>
138 <div class="question">
139 <p>Can I modify LLVM source code and redistribute the modified source?</p>
143 <p>Yes. The modified source distribution must retain the copyright notice and
144 follow the three bulletted conditions listed in
145 the <a href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM
149 <div class="question">
150 <p>Can I modify LLVM source code and redistribute binaries or other tools based
151 on it, without redistributing the source?</p>
155 <p>Yes. This is why we distribute LLVM under a less restrictive license than
156 GPL, as explained in the first question above.</p>
161 <!-- *********************************************************************** -->
163 <a name="source">Source Code</a>
165 <!-- *********************************************************************** -->
169 <div class="question">
170 <p>In what language is LLVM written?</p>
174 <p>All of the LLVM tools and libraries are written in C++ with extensive use of
178 <div class="question">
179 <p>How portable is the LLVM source code?</p>
183 <p>The LLVM source code should be portable to most modern UNIX-like operating
184 systems. Most of the code is written in standard C++ with operating system
185 services abstracted to a support library. The tools required to build and test
186 LLVM have been ported to a plethora of platforms.</p>
188 <p>Some porting problems may exist in the following areas:</p>
191 <li>The autoconf/makefile build system relies heavily on UNIX shell tools,
192 like the Bourne Shell and sed. Porting to systems without these tools
193 (MacOS 9, Plan 9) Will require more effort.</li>
200 <!-- *********************************************************************** -->
202 <a name="build">Build Problems</a>
204 <!-- *********************************************************************** -->
208 <div class="question">
209 <p>When I run configure, it finds the wrong C compiler.</p>
213 <p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
214 <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt>
215 and <tt>CXX</tt> for the C and C++ compiler, respectively.</p>
217 <p>If <tt>configure</tt> finds the wrong compiler, either adjust your
218 <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
223 <div class="question">
224 <p>The <tt>configure</tt> script finds the right C compiler, but it uses the
225 LLVM tools from a previous build. What do I do?</p>
229 <p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
230 if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
234 <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
235 program appears first in the <tt>PATH</tt>. This may work, but may not be
236 convenient when you want them <i>first</i> in your path for other
239 <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
240 correct. In a Bourne compatible shell, the syntax would be:</p>
242 <pre class="doc_code">
243 % PATH=[the path without the bad program] ./configure ...
246 <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
247 to do its work without having to adjust your <tt>PATH</tt>
248 permanently.</p></li>
252 <div class="question">
253 <p>When creating a dynamic library, I get a strange GLIBC error.</p>
257 <p>Under some operating systems (i.e. Linux), libtool does not work correctly if
258 GCC was compiled with the --disable-shared option. To work around this,
259 install your own version of GCC that has shared libraries enabled by
263 <div class="question">
264 <p>I've updated my source tree from Subversion, and now my build is trying to
265 use a file/directory that doesn't exist.</p>
269 <p>You need to re-run configure in your object directory. When new Makefiles
270 are added to the source tree, they have to be copied over to the object tree
271 in order to be used by the build.</p>
274 <div class="question">
275 <p>I've modified a Makefile in my source tree, but my build tree keeps using the
276 old version. What do I do?</p>
280 <p>If the Makefile already exists in your object tree, you can just run the
281 following command in the top level directory of your object tree:</p>
283 <pre class="doc_code">
284 % ./config.status <relative path to Makefile>
287 <p>If the Makefile is new, you will have to modify the configure script to copy
291 <div class="question">
292 <p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
297 <p>Sometimes, changes to the LLVM source code alters how the build system works.
298 Changes in libtool, autoconf, or header file dependencies are especially
299 prone to this sort of problem.</p>
301 <p>The best thing to try is to remove the old files and re-build. In most
302 cases, this takes care of the problem. To do this, just type <tt>make
303 clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
306 <div class="question">
307 <p>I've built LLVM and am testing it, but the tests freeze.</p>
311 <p>This is most likely occurring because you built a profile or release
312 (optimized) build of LLVM and have not specified the same information on the
313 <tt>gmake</tt> command line.</p>
315 <p>For example, if you built LLVM with the command:</p>
317 <pre class="doc_code">
318 % gmake ENABLE_PROFILING=1
321 <p>...then you must run the tests with the following commands:</p>
323 <pre class="doc_code">
325 % gmake ENABLE_PROFILING=1
329 <div class="question">
330 <p>Why do test results differ when I perform different types of builds?</p>
334 <p>The LLVM test suite is dependent upon several features of the LLVM tools and
337 <p>First, the debugging assertions in code are not enabled in optimized or
338 profiling builds. Hence, tests that used to fail may pass.</p>
340 <p>Second, some tests may rely upon debugging options or behavior that is only
341 available in the debug build. These tests will fail in an optimized or
345 <div class="question">
346 <p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
350 <p>This is <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392">a bug in
351 GCC</a>, and affects projects other than LLVM. Try upgrading or downgrading
355 <div class="question">
356 <p>Compiling LLVM with GCC succeeds, but the resulting tools do not work, what
361 <p>Several versions of GCC have shown a weakness in miscompiling the LLVM
362 codebase. Please consult your compiler version (<tt>gcc --version</tt>) to
363 find out whether it is <a href="GettingStarted.html#brokengcc">broken</a>.
364 If so, your only option is to upgrade GCC to a known good version.</p>
367 <div class="question">
368 <p>After Subversion update, rebuilding gives the error "No rule to make
373 <p>If the error is of the form:</p>
375 <pre class="doc_code">
376 gmake[2]: *** No rule to make target `/path/to/somefile', needed by
377 `/path/to/another/file.d'.<br>
381 <p>This may occur anytime files are moved within the Subversion repository or
382 removed entirely. In this case, the best solution is to erase all
383 <tt>.d</tt> files, which list dependencies for source files, and rebuild:</p>
385 <pre class="doc_code">
387 % rm -f `find . -name \*\.d`
391 <p>In other cases, it may be necessary to run <tt>make clean</tt> before
397 <!-- *********************************************************************** -->
399 <a name="felangs">Source Languages</a>
404 <div class="question">
405 <p><a name="langs">What source languages are supported?</a></p>
409 <p>LLVM currently has full support for C and C++ source languages. These are
410 available through both <a href="http://clang.llvm.org/">Clang</a> and
411 <a href="http://dragonegg.llvm.org/">DragonEgg</a>.</p>
413 <p>The PyPy developers are working on integrating LLVM into the PyPy backend so
414 that PyPy language can translate to LLVM.</p>
417 <div class="question">
418 <p><a name="langirgen">I'd like to write a self-hosting LLVM compiler. How
419 should I interface with the LLVM middle-end optimizers and back-end code
424 <p>Your compiler front-end will communicate with LLVM by creating a module in
425 the LLVM intermediate representation (IR) format. Assuming you want to write
426 your language's compiler in the language itself (rather than C++), there are
427 3 major ways to tackle generating LLVM IR from a front-end:</p>
430 <li><strong>Call into the LLVM libraries code using your language's FFI
431 (foreign function interface).</strong>
434 <li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc
437 <li><em>for:</em> enables running LLVM optimization passes without a
438 emit/parse overhead</li>
440 <li><em>for:</em> adapts well to a JIT context</li>
442 <li><em>against:</em> lots of ugly glue code to write</li>
445 <li> <strong>Emit LLVM assembly from your compiler's native language.</strong>
447 <li><em>for:</em> very straightforward to get started</li>
449 <li><em>against:</em> the .ll parser is slower than the bitcode reader
450 when interfacing to the middle end</li>
452 <li><em>against:</em> you'll have to re-engineer the LLVM IR object model
453 and asm writer in your language</li>
455 <li><em>against:</em> it may be harder to track changes to the IR</li>
458 <li><strong>Emit LLVM bitcode from your compiler's native language.</strong>
461 <li><em>for:</em> can use the more-efficient bitcode reader when
462 interfacing to the middle end</li>
464 <li><em>against:</em> you'll have to re-engineer the LLVM IR object
465 model and bitcode writer in your language</li>
467 <li><em>against:</em> it may be harder to track changes to the IR</li>
471 <p>If you go with the first option, the C bindings in include/llvm-c should help
472 a lot, since most languages have strong support for interfacing with C. The
473 most common hurdle with calling C from managed code is interfacing with the
474 garbage collector. The C interface was designed to require very little memory
475 management, and so is straightforward in this regard.</p>
478 <div class="question">
479 <p><a name="langhlsupp">What support is there for a higher level source language
480 constructs for building a compiler?</a></p>
484 <p>Currently, there isn't much. LLVM supports an intermediate representation
485 which is useful for code representation but will not support the high level
486 (abstract syntax tree) representation needed by most compilers. There are no
487 facilities for lexical nor semantic analysis.</p>
490 <div class="question">
491 <p><a name="getelementptr">I don't understand the GetElementPtr
492 instruction. Help!</a></p>
496 <p>See <a href="GetElementPtr.html">The Often Misunderstood GEP
502 <!-- *********************************************************************** -->
504 <a name="cfe">Using the C and C++ Front Ends</a>
509 <div class="question">
510 <p><a name="platformindependent">Can I compile C or C++ code to
511 platform-independent LLVM bitcode?</a></p>
515 <p>No. C and C++ are inherently platform-dependent languages. The most obvious
516 example of this is the preprocessor. A very common way that C code is made
517 portable is by using the preprocessor to include platform-specific code. In
518 practice, information about other platforms is lost after preprocessing, so
519 the result is inherently dependent on the platform that the preprocessing was
522 <p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to
523 vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to
524 a constant immediately, thus hard-wiring a platform-specific detail.</p>
526 <p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
527 lower-level than C, front-ends currently must emit platform-specific IR in
528 order to have the result conform to the platform ABI.</p>
533 <!-- *********************************************************************** -->
535 <a name="cfe_code">Questions about code generated by the demo page</a>
540 <div class="question">
541 <p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and
542 <tt>_GLOBAL__I_a...</tt> stuff that happens when I <tt>#include
543 <iostream></tt>?</a></p>
547 <p>If you <tt>#include</tt> the <tt><iostream></tt> header into a C++
548 translation unit, the file will probably use
549 the <tt>std::cin</tt>/<tt>std::cout</tt>/... global objects. However, C++
550 does not guarantee an order of initialization between static objects in
551 different translation units, so if a static ctor/dtor in your .cpp file
552 used <tt>std::cout</tt>, for example, the object would not necessarily be
553 automatically initialized before your use.</p>
555 <p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
556 STL that we use declares a static object that gets created in every
557 translation unit that includes <tt><iostream></tt>. This object has a
558 static constructor and destructor that initializes and destroys the global
559 iostream objects before they could possibly be used in the file. The code
560 that you see in the .ll file corresponds to the constructor and destructor
564 <p>If you would like to make it easier to <b>understand</b> the LLVM code
565 generated by the compiler in the demo page, consider using <tt>printf()</tt>
566 instead of <tt>iostream</tt>s to print values.</p>
569 <!--=========================================================================-->
571 <div class="question">
572 <p><a name="codedce">Where did all of my code go??</a></p>
576 <p>If you are using the LLVM demo page, you may often wonder what happened to
577 all of the code that you typed in. Remember that the demo script is running
578 the code through the LLVM optimizers, so if your code doesn't actually do
579 anything useful, it might all be deleted.</p>
581 <p>To prevent this, make sure that the code is actually needed. For example, if
582 you are computing some expression, return the value from the function instead
583 of leaving it in a local variable. If you really want to constrain the
584 optimizer, you can read from and assign to <tt>volatile</tt> global
588 <!--=========================================================================-->
590 <div class="question">
591 <p><a name="undef">What is this "<tt>undef</tt>" thing that shows up in my
596 <p><a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of
597 representing a value that is not defined. You can get these if you do not
598 initialize a variable before you use it. For example, the C function:</p>
600 <pre class="doc_code">
601 int X() { int i; return i; }
604 <p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has a
605 value specified for it.</p>
608 <!--=========================================================================-->
610 <div class="question">
611 <p><a name="callconvwrong">Why does instcombine + simplifycfg turn
612 a call to a function with a mismatched calling convention into "unreachable"?
613 Why not make the verifier reject it?</a></p>
617 <p>This is a common problem run into by authors of front-ends that are using
618 custom calling conventions: you need to make sure to set the right calling
619 convention on both the function and on each call to the function. For example,
622 <pre class="doc_code">
623 define fastcc void @foo() {
632 <p>Is optimized to:</p>
634 <pre class="doc_code">
635 define fastcc void @foo() {
643 <p>... with "opt -instcombine -simplifycfg". This often bites people because
644 "all their code disappears". Setting the calling convention on the caller and
645 callee is required for indirect calls to work, so people often ask why not make
646 the verifier reject this sort of thing.</p>
648 <p>The answer is that this code has undefined behavior, but it is not illegal.
649 If we made it illegal, then every transformation that could potentially create
650 this would have to ensure that it doesn't, and there is valid code that can
651 create this sort of construct (in dead code). The sorts of things that can
652 cause this to happen are fairly contrived, but we still need to accept them.
653 Here's an example:</p>
655 <pre class="doc_code">
656 define fastcc void @foo() {
659 define internal void @bar(void()* %FP, i1 %cond) {
660 br i1 %cond, label %T, label %F
665 call fastcc void %FP()
668 define void @test() {
669 %X = or i1 false, false
670 call void @bar(void()* @foo, i1 %X)
675 <p>In this example, "test" always passes @foo/false into bar, which ensures that
676 it is dynamically called with the right calling conv (thus, the code is
677 perfectly well defined). If you run this through the inliner, you get this
678 (the explicit "or" is there so that the inliner doesn't dead code eliminate
682 <pre class="doc_code">
683 define fastcc void @foo() {
686 define void @test() {
687 %X = or i1 false, false
688 br i1 %X, label %T.i, label %F.i
693 call fastcc void @foo()
700 <p>Here you can see that the inlining pass made an undefined call to @foo with
701 the wrong calling convention. We really don't want to make the inliner have
702 to know about this sort of thing, so it needs to be valid code. In this case,
703 dead code elimination can trivially remove the undefined code. However, if %X
704 was an input argument to @test, the inliner would produce this:
707 <pre class="doc_code">
708 define fastcc void @foo() {
712 define void @test(i1 %X) {
713 br i1 %X, label %T.i, label %F.i
718 call fastcc void @foo()
725 <p>The interesting thing about this is that %X <em>must</em> be false for the
726 code to be well-defined, but no amount of dead code elimination will be able to
727 delete the broken call as unreachable. However, since instcombine/simplifycfg
728 turns the undefined call into unreachable, we end up with a branch on a
729 condition that goes to unreachable: a branch to unreachable can never happen, so
730 "-inline -instcombine -simplifycfg" is able to produce:</p>
732 <pre class="doc_code">
733 define fastcc void @foo() {
736 define void @test(i1 %X) {
738 call fastcc void @foo()
747 <!-- *********************************************************************** -->
751 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
752 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
753 <a href="http://validator.w3.org/check/referer"><img
754 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
756 <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
757 Last modified: $Date$