<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM: Frequently Asked Questions</title>
<style type="text/css">
- @import url("llvm.css");
+ @import url("_static/llvm.css");
.question { font-weight: bold }
.answer { margin-left: 2em }
</style>
</head>
<body>
-<div class="doc_title">
+<h1>
LLVM: Frequently Asked Questions
-</div>
+</h1>
<ol>
<li><a href="#license">License</a>
<ol>
- <li>Why are the LLVM source code and the front-end distributed under
- different licenses?</li>
-
<li>Does the University of Illinois Open Source License really qualify as an
"open source" license?</li>
<li>After Subversion update, rebuilding gives the error "No rule to make
target".</li>
- <li><a href="#llvmc">The <tt>llvmc</tt> program gives me errors/doesn't
- work.</a></li>
-
- <li><a href="#srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir,
- it fails. Why?</a></li>
</ol></li>
<li><a href="#felangs">Source Languages</a>
instruction. Help!</a></li>
</ol>
- <li><a href="#cfe">Using the GCC Front End</a>
+ <li><a href="#cfe">Using the C and C++ Front Ends</a>
<ol>
- <li>When I compile software that uses a configure script, the configure
- script thinks my system has all of the header files and libraries it is
- testing for. How do I get configure to work correctly?</li>
-
- <li>When I compile code using the LLVM GCC front end, it complains that it
- cannot find libcrtend.a?</li>
-
- <li>How can I disable all optimizations when compiling code using the LLVM
- GCC front end?</li>
-
- <li><a href="#translatecxx">Can I use LLVM to convert C++ code to C
- code?</a></li>
-
<li><a href="#platformindependent">Can I compile C or C++ code to
platform-independent LLVM bitcode?</a></li>
</ol>
</li>
- <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
+ <li><a href="#cfe_code">Questions about code generated by the demo page</a>
<ol>
<li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
- <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
+ <tt>_GLOBAL__I_a...</tt> stuff that happens when I
#include <iostream>?</a></li>
<li><a href="#codedce">Where did all of my code go??</a></li>
<li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in
my code?</a></li>
+
+ <li><a href="#callconvwrong">Why does instcombine + simplifycfg turn
+ a call to a function with a mismatched calling convention into "unreachable"?
+ Why not make the verifier reject it?</a></li>
</ol>
</li>
</ol>
<div class="doc_author">
- <p>Written by <a href="http://llvm.org">The LLVM Team</a></p>
+ <p>Written by <a href="http://llvm.org/">The LLVM Team</a></p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="license">License</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="question">
-<p>Why are the LLVM source code and the front-end distributed under different
- licenses?</p>
-</div>
-
-<div class="answer">
-<p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
- Our aim is to distribute LLVM source code under a <em>much less
- restrictive</em> license, in particular one that does not compel users who
- distribute tools based on modifying the source to redistribute the modified
- source code as well.</p>
-</div>
+<div>
<div class="question">
<p>Does the University of Illinois Open Source License really qualify as an
GPL, as explained in the first question above.</p>
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="source">Source Code</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
+<div>
+
<div class="question">
<p>In what language is LLVM written?</p>
</div>
<p>Some porting problems may exist in the following areas:</p>
<ul>
- <li>The GCC front end code is not as portable as the LLVM suite, so it may not
- compile as well on unsupported platforms.</li>
-
- <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
- Shell and sed. Porting to systems without these tools (MacOS 9, Plan 9)
- will require more effort.</li>
+ <li>The autoconf/makefile build system relies heavily on UNIX shell tools,
+ like the Bourne Shell and sed. Porting to systems without these tools
+ (MacOS 9, Plan 9) Will require more effort.</li>
</ul>
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="build">Build Problems</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
+<div>
+
<div class="question">
<p>When I run configure, it finds the wrong C compiler.</p>
</div>
<div class="question">
<p>The <tt>configure</tt> script finds the right C compiler, but it uses the
- LLVM linker from a previous build. What do I do?</p>
+ LLVM tools from a previous build. What do I do?</p>
</div>
<div class="answer">
work.</p></li>
<li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
- correct. In a Borne compatible shell, the syntax would be:</p>
+ correct. In a Bourne compatible shell, the syntax would be:</p>
<pre class="doc_code">
% PATH=[the path without the bad program] ./configure ...
rebuilding.</p>
</div>
-<div class="question">
-<p><a name="llvmc">The <tt>llvmc</tt> program gives me errors/doesn't
- work.</a></p>
-</div>
-
-<div class="answer">
-<p><tt>llvmc</tt> is experimental and isn't really supported. We suggest
- using <tt>llvm-gcc</tt> instead.</p>
-</div>
-
-<div class="question">
-<p><a name="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it
- fails. Why?</a></p>
-</div>
-
-<div class="answer">
-<p>The <tt>GNUmakefile</tt> in the top-level directory of LLVM-GCC is a special
- <tt>Makefile</tt> used by Apple to invoke the <tt>build_gcc</tt> script after
- setting up a special environment. This has the unforunate side-effect that
- trying to build LLVM-GCC with srcdir == objdir in a "non-Apple way" invokes
- the <tt>GNUmakefile</tt> instead of <tt>Makefile</tt>. Because the
- environment isn't set up correctly to do this, the build fails.</p>
-
-<p>People not building LLVM-GCC the "Apple way" need to build LLVM-GCC with
- srcdir != objdir, or simply remove the GNUmakefile entirely.</p>
-
-<p>We regret the inconvenience.</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section"><a name="felangs">Source Languages</a></div>
+<h2>
+ <a name="felangs">Source Languages</a>
+</h2>
+
+<div>
<div class="question">
<p><a name="langs">What source languages are supported?</a></p>
<div class="answer">
<p>LLVM currently has full support for C and C++ source languages. These are
- available through a special version of GCC that LLVM calls the
- <a href="#cfe">C Front End</a></p>
-
-<p>There is an incomplete version of a Java front end available in the
- <tt>java</tt> module. There is no documentation on this yet so you'll need to
- download the code, compile it, and try it.</p>
+ available through both <a href="http://clang.llvm.org/">Clang</a> and
+ <a href="http://dragonegg.llvm.org/">DragonEgg</a>.</p>
<p>The PyPy developers are working on integrating LLVM into the PyPy backend so
that PyPy language can translate to LLVM.</p>
<p>Currently, there isn't much. LLVM supports an intermediate representation
which is useful for code representation but will not support the high level
(abstract syntax tree) representation needed by most compilers. There are no
- facilities for lexical nor semantic analysis. There is, however, a <i>mostly
- implemented</i> configuration-driven
- <a href="CompilerDriver.html">compiler driver</a> which simplifies the task
- of running optimizations, linking, and executable generation.</p>
+ facilities for lexical nor semantic analysis.</p>
</div>
<div class="question">
Instruction</a>.</p>
</div>
-<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="cfe">Using the GCC Front End</a>
-</div>
-
-<div class="question">
-<p>When I compile software that uses a configure script, the configure script
- thinks my system has all of the header files and libraries it is testing for.
- How do I get configure to work correctly?</p>
-</div>
-
-<div class="answer">
-<p>The configure script is getting things wrong because the LLVM linker allows
- symbols to be undefined at link time (so that they can be resolved during JIT
- or translation to the C back end). That is why configure thinks your system
- "has everything."</p>
-
-<p>To work around this, perform the following steps:</p>
-
-<ol>
- <li>Make sure the CC and CXX environment variables contains the full path to
- the LLVM GCC front end.</li>
-
- <li>Make sure that the regular C compiler is first in your PATH. </li>
-
- <li>Add the string "-Wl,-native" to your CFLAGS environment variable.</li>
-</ol>
-
-<p>This will allow the <tt>llvm-ld</tt> linker to create a native code
- executable instead of shell script that runs the JIT. Creating native code
- requires standard linkage, which in turn will allow the configure script to
- find out if code is not linking on your system because the feature isn't
- available on your system.</p>
-</div>
-
-<div class="question">
-<p>When I compile code using the LLVM GCC front end, it complains that it cannot
- find libcrtend.a.
-</p>
-</div>
-
-<div class="answer">
-<p>The only way this can happen is if you haven't installed the runtime
- library. To correct this, do:</p>
-
-<pre class="doc_code">
-% cd llvm/runtime
-% make clean ; make install-bytecode
-</pre>
-</div>
-
-<div class="question">
-<p>How can I disable all optimizations when compiling code using the LLVM GCC
- front end?</p>
-</div>
-
-<div class="answer">
-<p>Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and
- optimizations done at the llvm level, leaving you with the truly horrible
- code that you desire.</p>
-</div>
-
-
-<div class="question">
-<p><a name="translatecxx">Can I use LLVM to convert C++ code to C code?</a></p>
</div>
-<div class="answer">
-<p>Yes, you can use LLVM to convert code from any language LLVM supports to C.
- Note that the generated C code will be very low level (all loops are lowered
- to gotos, etc) and not very pretty (comments are stripped, original source
- formatting is totally lost, variables are renamed, expressions are
- regrouped), so this may not be what you're looking for. Also, there are
- several limitations noted below.<p>
-
-<p>Use commands like this:</p>
-
-<ol>
- <li><p>Compile your program as normal with llvm-g++:</p>
-
-<pre class="doc_code">
-% llvm-g++ x.cpp -o program
-</pre>
-
- <p>or:</p>
-
-<pre class="doc_code">
-% llvm-g++ a.cpp -c
-% llvm-g++ b.cpp -c
-% llvm-g++ a.o b.o -o program
-</pre>
-
- <p>With llvm-gcc3, this will generate program and program.bc. The .bc
- file is the LLVM version of the program all linked together.</p></li>
-
- <li><p>Convert the LLVM code to C code, using the LLC tool with the C
- backend:</p>
-
-<pre class="doc_code">
-% llc -march=c program.bc -o program.c
-</pre></li>
-
- <li><p>Finally, compile the C file:</p>
-
-<pre class="doc_code">
-% cc x.c
-</pre></li>
-
-</ol>
-
-<p>Using LLVM does not eliminate the need for C++ library support. If you use
- the llvm-g++ front-end, the generated code will depend on g++'s C++ support
- libraries in the same way that code generated from g++ would. If you use
- another C++ front-end, the generated code will depend on whatever library
- that front-end would normally require.</p>
-
-<p>If you are working on a platform that does not provide any C++ libraries, you
- may be able to manually compile libstdc++ to LLVM bitcode, statically link it
- into your program, then use the commands above to convert the whole result
- into C code. Alternatively, you might compile the libraries and your
- application into two different chunks of C code and link them.</p>
+<!-- *********************************************************************** -->
+<h2>
+ <a name="cfe">Using the C and C++ Front Ends</a>
+</h2>
-<p>Note that, by default, the C back end does not support exception handling.
- If you want/need it for a certain program, you can enable it by passing
- "-enable-correct-eh-support" to the llc program. The resultant code will use
- setjmp/longjmp to implement exception support that is relatively slow, and
- not C++-ABI-conforming on most platforms, but otherwise correct.</p>
-
-<p>Also, there are a number of other limitations of the C backend that cause it
- to produce code that does not fully conform to the C++ ABI on most
- platforms. Some of the C++ programs in LLVM's test suite are known to fail
- when compiled with the C back end because of ABI incompatiblities with
- standard C++ libraries.</p>
-</div>
+<div>
<div class="question">
<p><a name="platformindependent">Can I compile C or C++ code to
portable is by using the preprocessor to include platform-specific code. In
practice, information about other platforms is lost after preprocessing, so
the result is inherently dependent on the platform that the preprocessing was
- targetting.</p>
+ targeting.</p>
<p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to
vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to
- a constant immediately, thus hardwaring a platform-specific detail.</p>
+ a constant immediately, thus hard-wiring a platform-specific detail.</p>
<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
lower-level than C, front-ends currently must emit platform-specific IR in
order to have the result conform to the platform ABI.</p>
</div>
-<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="cfe_code">Questions about code generated by the GCC front-end</a>
</div>
+<!-- *********************************************************************** -->
+<h2>
+ <a name="cfe_code">Questions about code generated by the demo page</a>
+</h2>
+
+<div>
+
<div class="question">
<p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and
- <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I <tt>#include
+ <tt>_GLOBAL__I_a...</tt> stuff that happens when I <tt>#include
<iostream></tt>?</a></p>
</div>
value specified for it.</p>
</div>
+<!--=========================================================================-->
+
+<div class="question">
+<p><a name="callconvwrong">Why does instcombine + simplifycfg turn
+ a call to a function with a mismatched calling convention into "unreachable"?
+ Why not make the verifier reject it?</a></p>
+</div>
+
+<div class="answer">
+<p>This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For example,
+this code:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @bar() {
+ call void @foo()
+ ret void
+}
+</pre>
+
+<p>Is optimized to:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @bar() {
+ unreachable
+}
+</pre>
+
+<p>... with "opt -instcombine -simplifycfg". This often bites people because
+"all their code disappears". Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not make
+the verifier reject this sort of thing.</p>
+
+<p>The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn't, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here's an example:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define internal void @bar(void()* %FP, i1 %cond) {
+ br i1 %cond, label %T, label %F
+T:
+ call void %FP()
+ ret void
+F:
+ call fastcc void %FP()
+ ret void
+}
+define void @test() {
+ %X = or i1 false, false
+ call void @bar(void()* @foo, i1 %X)
+ ret void
+}
+</pre>
+
+<p>In this example, "test" always passes @foo/false into bar, which ensures that
+ it is dynamically called with the right calling conv (thus, the code is
+ perfectly well defined). If you run this through the inliner, you get this
+ (the explicit "or" is there so that the inliner doesn't dead code eliminate
+ a bunch of stuff):
+</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @test() {
+ %X = or i1 false, false
+ br i1 %X, label %T.i, label %F.i
+T.i:
+ call void @foo()
+ br label %bar.exit
+F.i:
+ call fastcc void @foo()
+ br label %bar.exit
+bar.exit:
+ ret void
+}
+</pre>
+
+<p>Here you can see that the inlining pass made an undefined call to @foo with
+ the wrong calling convention. We really don't want to make the inliner have
+ to know about this sort of thing, so it needs to be valid code. In this case,
+ dead code elimination can trivially remove the undefined code. However, if %X
+ was an input argument to @test, the inliner would produce this:
+</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+
+define void @test(i1 %X) {
+ br i1 %X, label %T.i, label %F.i
+T.i:
+ call void @foo()
+ br label %bar.exit
+F.i:
+ call fastcc void @foo()
+ br label %bar.exit
+bar.exit:
+ ret void
+}
+</pre>
+
+<p>The interesting thing about this is that %X <em>must</em> be false for the
+code to be well-defined, but no amount of dead code elimination will be able to
+delete the broken call as unreachable. However, since instcombine/simplifycfg
+turns the undefined call into unreachable, we end up with a branch on a
+condition that goes to unreachable: a branch to unreachable can never happen, so
+"-inline -instcombine -simplifycfg" is able to produce:</p>
+
+<pre class="doc_code">
+define fastcc void @foo() {
+ ret void
+}
+define void @test(i1 %X) {
+F.i:
+ call fastcc void @foo()
+ ret void
+}
+</pre>
+
+</div>
+
+</div>
+
<!-- *********************************************************************** -->
<hr>
<a href="http://validator.w3.org/check/referer"><img
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
- <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff