diff options
Diffstat (limited to 'docs/FAQ.html')
| -rw-r--r-- | docs/FAQ.html | 713 |
1 files changed, 713 insertions, 0 deletions
diff --git a/docs/FAQ.html b/docs/FAQ.html new file mode 100644 index 0000000..96360d0 --- /dev/null +++ b/docs/FAQ.html @@ -0,0 +1,713 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>LLVM: Frequently Asked Questions</title> + <style type="text/css"> + @import url("llvm.css"); + .question { font-weight: bold } + .answer { margin-left: 2em } + </style> +</head> +<body> + +<div class="doc_title"> + LLVM: Frequently Asked Questions +</div> + +<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>Can I modify LLVM source code and redistribute the modified source?</li> + <li>Can I modify LLVM source code and redistribute binaries or other tools + based on it, without redistributing the source?</li> + </ol></li> + + <li><a href="#source">Source code</a> + <ol> + <li>In what language is LLVM written?</li> + <li>How portable is the LLVM source code?</li> + </ol></li> + + <li><a href="#build">Build Problems</a> + <ol> + <li>When I run configure, it finds the wrong C compiler.</li> + <li>The <tt>configure</tt> script finds the right C compiler, but it uses the + LLVM linker from a previous build. What do I do?</li> + <li>When creating a dynamic library, I get a strange GLIBC error.</li> + <li>I've updated my source tree from Subversion, and now my build is trying + to use a file/directory that doesn't exist.</li> + <li>I've modified a Makefile in my source tree, but my build tree keeps using + the old version. What do I do?</li> + <li>I've upgraded to a new version of LLVM, and I get strange build + errors.</li> + <li>I've built LLVM and am testing it, but the tests freeze.</li> + <li>Why do test results differ when I perform different types of builds?</li> + <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li> + <li>When I use the test suite, all of the C Backend tests fail. What is + wrong?</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.</li></a> + </ol></li> + + <li><a href="#felangs">Source Languages</a> + <ol> + <li><a href="#langs">What source languages are supported?</a></li> + <li><a href="#langhlsupp">What support is there for higher level source + language constructs for building a compiler?</a></li> + <li><a href="GetElementPtr.html">I don't understand the GetElementPtr + instruction. Help!</a></li> + </ol> + + <li><a href="#cfe">Using the GCC Front End</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="#translatec++">Can I use LLVM to convert C++ code to C code?</a></li> + + </ol> + </li> + + <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a> + <ol> + <li><a href="#__main">What is this <tt>__main()</tt> call that gets inserted into + <tt>main()</tt>?</a></li> + <li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and + <tt>_GLOBAL__I__tmp_webcompile...</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> + </ol> + </li> +</ol> + +<div class="doc_author"> + <p>Written by <a href="http://llvm.org">The LLVM Team</a></p> +</div> + + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="license">License</a> +</div> +<!-- *********************************************************************** --> + +<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 class="question"> +<p>Does the University of Illinois Open Source License really qualify as an +"open source" license?</p> +</div> + +<div class="answer"> +<p>Yes, the license is <a +href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open +Source Initiative (OSI).</p> +</div> + +<div class="question"> +<p>Can I modify LLVM source code and redistribute the modified source?</p> +</div> + +<div class="answer"> +<p>Yes. The modified source distribution must retain the copyright notice and +follow the three bulletted conditions listed in the <a +href="http://llvm.org/releases/1.3/LICENSE.TXT">LLVM license</a>.</p> +</div> + +<div class="question"> +<p>Can I modify LLVM source code and redistribute binaries or other tools based +on it, without redistributing the source?</p> +</div> + +<div class="answer"> +<p>Yes, this is why we distribute LLVM under a less restrictive license than +GPL, as explained in the first question above.</p> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="source">Source Code</a> +</div> +<!-- *********************************************************************** --> + +<div class="question"> +<p>In what language is LLVM written?</p> +</div> + +<div class="answer"> +<p>All of the LLVM tools and libraries are written in C++ with extensive use of +the STL.</p> +</div> + +<div class="question"> +<p>How portable is the LLVM source code?</p> +</div> + +<div class="answer"> +<p>The LLVM source code should be portable to most modern UNIX-like operating +systems. Most of the code is written in standard C++ with operating system +services abstracted to a support library. The tools required to build and test +LLVM have been ported to a plethora of platforms.</p> + +<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> + +</ul> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="build">Build Problems</a> +</div> +<!-- *********************************************************************** --> + +<div class="question"> +<p>When I run configure, it finds the wrong C compiler.</p> +</div> + +<div class="answer"> + +<p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then +<tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt> and <tt>CXX</tt> +for the C and C++ compiler, respectively.</p> + +<p>If <tt>configure</tt> finds the wrong compiler, either adjust your +<tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt> +explicitly.</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> +</div> + +<div class="answer"> +<p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so +if it's grabbing the wrong linker/assembler/etc, there are two ways to fix +it:</p> + +<ol> + + <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct + program appears first in the <tt>PATH</tt>. This may work, but may not be + convenient when you want them <i>first</i> in your path for other + 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> + + <p><tt>PATH=[the path without the bad program] ./configure ...</tt></p> + + <p>This is still somewhat inconvenient, but it allows <tt>configure</tt> + to do its work without having to adjust your <tt>PATH</tt> + permanently.</p></li> + +</ol> + +</div> + +<div class="question"> +<p>When creating a dynamic library, I get a strange GLIBC error.</p> +</div> + +<div class="answer"> +<p>Under some operating systems (i.e. Linux), libtool does not work correctly if +GCC was compiled with the --disable-shared option. To work around this, install +your own version of GCC that has shared libraries enabled by default.</p> +</div> + +<div class="question"> + <p>I've updated my source tree from Subversion, and now my build is trying to + use a file/directory that doesn't exist.</p> +</div> + +<div class="answer"> +<p>You need to re-run configure in your object directory. When new Makefiles +are added to the source tree, they have to be copied over to the object tree in +order to be used by the build.</p> +</div> + +<div class="question"> +<p>I've modified a Makefile in my source tree, but my build tree keeps using the +old version. What do I do?</p> +</div> + +<div class="answer"> + +<p>If the Makefile already exists in your object tree, you +can just run the following command in the top level directory of your object +tree:</p> + +<p><tt>./config.status <relative path to Makefile></tt><p> + +<p>If the Makefile is new, you will have to modify the configure script to copy +it over.</p> + +</div> + +<div class="question"> +<p>I've upgraded to a new version of LLVM, and I get strange build errors.</p> +</div> + +<div class="answer"> + +<p>Sometimes, changes to the LLVM source code alters how the build system works. +Changes in libtool, autoconf, or header file dependencies are especially prone +to this sort of problem.</p> + +<p>The best thing to try is to remove the old files and re-build. In most +cases, this takes care of the problem. To do this, just type <tt>make +clean</tt> and then <tt>make</tt> in the directory that fails to build.</p> + +</div> + +<div class="question"> +<p>I've built LLVM and am testing it, but the tests freeze.</p> +</div> + +<div class="answer"> + +<p>This is most likely occurring because you built a profile or release +(optimized) build of LLVM and have not specified the same information on the +<tt>gmake</tt> command line.</p> + +<p>For example, if you built LLVM with the command:</p> + +<div class="doc_code"> +<pre> +% gmake ENABLE_PROFILING=1 +</pre> +</div> + +<p>...then you must run the tests with the following commands:</p> + +<div class="doc_code"> +<pre> +% cd llvm/test +% gmake ENABLE_PROFILING=1 +</pre> +</div> + +</div> + +<div class="question"> +<p>Why do test results differ when I perform different types of builds?</p> +</div> + +<div class="answer"> + +<p>The LLVM test suite is dependent upon several features of the LLVM tools and +libraries.</p> + +<p>First, the debugging assertions in code are not enabled in optimized or +profiling builds. Hence, tests that used to fail may pass.</p> + +<p>Second, some tests may rely upon debugging options or behavior that is only +available in the debug build. These tests will fail in an optimized or profile +build.</p> + +</div> + +<div class="question"> +<p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p> +</div> + +<div class="answer"> +<p>This is <a href="http://gcc.gnu.org/PR?13392">a bug in GCC</a>, and + affects projects other than LLVM. Try upgrading or downgrading your GCC.</p> +</div> + +<div class="question"> + <p>After Subversion update, rebuilding gives the error + "No rule to make target".</p> +</div> + +<div class="answer"> +<p>If the error is of the form:</p> + +<div class="doc_code"> +<pre> +gmake[2]: *** No rule to make target `/path/to/somefile', needed by +`/path/to/another/file.d'.<br> +Stop. +</pre> +</div> + +<p>This may occur anytime files are moved within the Subversion repository or +removed entirely. In this case, the best solution is to erase all +<tt>.d</tt> files, which list dependencies for source files, and rebuild:</p> + +<div class="doc_code"> +<pre> +% cd $LLVM_OBJ_DIR +% rm -f `find . -name \*\.d` +% gmake +</pre> +</div> + +<p>In other cases, it may be necessary to run <tt>make clean</tt> before +rebuilding.</p> +</div> + +<div class="question"> + <a name="llvmc"<p>The <tt>llvmc</tt> program gives me errors/doesn't + work.</p></a> +</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="doc_section"><a name="felangs">Source Languages</a></div> + +<div class="question"><p> + <a name="langs">What source languages are supported?</a></p> +</div> +<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> + <p>In the <tt>stacker</tt> module is a compiler and runtime + library for the Stacker language, a "toy" language loosely based on Forth.</p> + <p>The PyPy developers are working on integrating LLVM into the PyPy backend + so that PyPy language can translate to LLVM.</p> +</div> +<div class="question"><a name="langhlsupp"> + <p>What support is there for a higher level source language constructs for + building a compiler?</a></p> +</div> +<div class="answer"> + <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> +</div> + +<div class="question"><a name="langhlsupp"> + <p>I don't understand the GetElementPtr + instruction. Help!</a></p> +</div> +<div class="answer"> + <p>See <a href="GetElementPtr.html">The Often Misunderstood GEP + Instruction</a>.</li> +</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> + +<div class="doc_code"> +<pre> +% cd llvm/runtime +% make clean ; make install-bytecode +</pre> +</div> +</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="translatec++">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. However, this is a good way to add +C++ support for a processor that does not otherwise have a C++ compiler. +</p> + +<p>Use commands like this:</p> + +<ol> +<li><p>Compile your program as normal with llvm-g++:</p></li> + +<div class="doc_code"> +<pre> +% llvm-g++ x.cpp -o program +</pre> +</div> + +<p>or:</p> + +<div class="doc_code"> +<pre> +% llvm-g++ a.cpp -c +% llvm-g++ b.cpp -c +% llvm-g++ a.o b.o -o program +</pre> +</div> + +<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><p>Convert the LLVM code to C code, using the LLC tool with the C +backend:</p></li> + +<div class="doc_code"> +<pre> +% llc -march=c program.bc -o program.c +</pre> +</div> + +<li><p>Finally, compile the c file:</p></li> + +<div class="doc_code"> +<pre> +% cc x.c +</pre> +</div> + +</ol> + +<p>Note that, by default, the C backend 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 correct but +relatively slow. +</p> + +<p>Also note: this specific sequence of commands won't work if you use a +function defined in the C++ runtime library (or any other C++ library). To +access an external C++ library, you must 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 can compile the libraries and your application into two different chunks +of C code and link them.</p> + +</div> + + + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="cfe_code">Questions about code generated by the GCC front-end</a> +</div> + +<div class="question"><p> +<a name="__main"></a> +What is this <tt>__main()</tt> call that gets inserted into <tt>main()</tt>? +</p></div> + +<div class="answer"> +<p> +The <tt>__main</tt> call is inserted by the C/C++ compiler in order to guarantee +that static constructors and destructors are called when the program starts up +and shuts down. In C, you can create static constructors and destructors by +using GCC extensions, and in C++ you can do so by creating a global variable +whose class has a ctor or dtor. +</p> + +<p> +The actual implementation of <tt>__main</tt> lives in the +<tt>llvm/runtime/GCCLibraries/crtend/</tt> directory in the source-base, and is +linked in automatically when you link the program. +</p> +</div> + +<!--=========================================================================--> + +<div class="question"> +<a name="iosinit"></a> +<p> What is this <tt>llvm.global_ctors</tt> and +<tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I #include +<iostream>?</p> +</div> + +<div class="answer"> + +<p>If you #include the <iostream> header into a C++ translation unit, the +file will probably use the <tt>std::cin</tt>/<tt>std::cout</tt>/... global +objects. However, C++ does not guarantee an order of initialization between +static objects in different translation units, so if a static ctor/dtor in your +.cpp file used <tt>std::cout</tt>, for example, the object would not necessarily +be automatically initialized before your use.</p> + +<p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the +STL that we use declares a static object that gets created in every translation +unit that includes <tt><iostream></tt>. This object has a static +constructor and destructor that initializes and destroys the global iostream +objects before they could possibly be used in the file. The code that you see +in the .ll file corresponds to the constructor and destructor registration code. +</p> + +<p>If you would like to make it easier to <b>understand</b> the LLVM code +generated by the compiler in the demo page, consider using <tt>printf()</tt> +instead of <tt>iostream</tt>s to print values.</p> + +</div> + +<!--=========================================================================--> + +<div class="question"><p> +<a name="codedce"></a> +Where did all of my code go?? +</p></div> + +<div class="answer"> +<p> +If you are using the LLVM demo page, you may often wonder what happened to all +of the code that you typed in. Remember that the demo script is running the +code through the LLVM optimizers, so if your code doesn't actually do anything +useful, it might all be deleted. +</p> + +<p> +To prevent this, make sure that the code is actually needed. For example, if +you are computing some expression, return the value from the function instead of +leaving it in a local variable. If you really want to constrain the optimizer, +you can read from and assign to <tt>volatile</tt> global variables. +</p> +</div> + +<!--=========================================================================--> + +<div class="question"><p> +<a name="undef"></a> +<p>What is this "<tt>undef</tt>" thing that shows up in my code? +</p></div> + +<div class="answer"> +<p> +<a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of representing +a value that is not defined. You can get these if you do not initialize a +variable before you use it. For example, the C function:</p> + +<div class="doc_code"> +<pre> +int X() { int i; return i; } +</pre> +</div> + +<p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has +a value specified for it.</p> +</div> + +<!-- *********************************************************************** --> + +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a> + + <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> + +</body> +</html> |