Does the University of Illinois Open Source License really qualify as an -"open source" license?
+ "open source" license?Yes, the license is certified by the Open -Source Initiative (OSI).
+Yes, the license + is certified by + the Open Source Initiative (OSI).
Yes. The modified source distribution must retain the copyright notice and -follow the three bulletted conditions listed in the LLVM license.
+ follow the three bulletted conditions listed in + the LLVM + license.Can I modify LLVM source code and redistribute binaries or other tools based -on it, without redistributing the source?
+ on it, without redistributing the source?Yes, this is why we distribute LLVM under a less restrictive license than -GPL, as explained in the first question above.
+Yes. This is why we distribute LLVM under a less restrictive license than + GPL, as explained in the first question above.
+Source Code -
In what language is LLVM written?
All of the LLVM tools and libraries are written in C++ with extensive use of -the STL.
+ the STL.Some porting problems may exist in the following areas:
-
-
-
- The GCC front end code is not as portable as the LLVM suite, so it may not - compile as well on unsupported platforms. - -
- 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. - +
- 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.
Build Problems -
When I run configure, it finds the wrong C compiler.
The configure script attempts to locate first gcc and then -cc, unless it finds compiler paths set in CC and CXX -for the C and C++ compiler, respectively.
+ cc, unless it finds compiler paths set in CC + and CXX for the C and C++ compiler, respectively.If configure finds the wrong compiler, either adjust your -PATH environment variable or set CC and CXX -explicitly.
+ PATH environment variable or set CC and CXX + explicitly.The configure script finds the right C compiler, but it uses the -LLVM linker from a previous build. What do I do?
+ LLVM tools from a previous build. What do I do?The configure script uses the PATH to find executables, so -if it's grabbing the wrong linker/assembler/etc, there are two ways to fix -it:
+ if it's grabbing the wrong linker/assembler/etc, there are two ways to fix + it:-
-
Adjust your PATH environment variable so that the correct - program appears first in the PATH. This may work, but may not be - convenient when you want them first in your path for other - work.
+ program appears first in the PATH. This may work, but may not be
+ convenient when you want them first in your path for other
+ work.
Run configure with an alternative PATH that is - correct. In a Borne compatible shell, the syntax would be:
- -PATH=[the path without the bad program] ./configure ...
+ correct. In a Bourne compatible shell, the syntax would be: + ++% PATH=[the path without the bad program] ./configure ... +
This is still somewhat inconvenient, but it allows configure - to do its work without having to adjust your PATH - permanently.
-
+ to do its work without having to adjust your PATH
+ permanently.
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.
+ 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.I've updated my source tree from CVS, and now my build is trying to use a -file/directory that doesn't exist.
+I've updated my source tree from Subversion, and now my build is trying to + use a file/directory that doesn't exist.
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.
+ are added to the source tree, they have to be copied over to the object tree + in order to be used by the build.I've modified a Makefile in my source tree, but my build tree keeps using the -old version. What do I do?
+ old version. What do I do?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:
-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:
- -./config.status <relative path to Makefile>
+
+% ./config.status <relative path to Makefile> +
If the Makefile is new, you will have to modify the configure script to copy -it over.
- + it over.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.
+ Changes in libtool, autoconf, or header file dependencies are especially + prone to this sort of problem.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 make -clean and then make in the directory that fails to build.
- + cases, this takes care of the problem. To do this, just type make + clean and then make in the directory that fails to build.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 -gmake command line.
+ (optimized) build of LLVM and have not specified the same information on the + gmake command line.For example, if you built LLVM with the command:
-+% gmake ENABLE_PROFILING=1-
...then you must run the tests with the following commands:
-+% cd llvm/test % gmake ENABLE_PROFILING=1
Why do test results differ when I perform different types of builds?
The LLVM test suite is dependent upon several features of the LLVM tools and -libraries.
+ libraries.First, the debugging assertions in code are not enabled in optimized or -profiling builds. Hence, tests that used to fail may pass.
+ profiling builds. Hence, tests that used to fail may pass.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.
- + available in the debug build. These tests will fail in an optimized or + profile build.This is a bug in GCC, and - affects projects other than LLVM. Try upgrading or downgrading your GCC.
+This is a bug in + GCC, and affects projects other than LLVM. Try upgrading or downgrading + your GCC.
+Compiling LLVM with GCC succeeds, but the resulting tools do not work, what + can be wrong?
+Several versions of GCC have shown a weakness in miscompiling the LLVM + codebase. Please consult your compiler version (gcc --version) to + find out whether it is broken. + If so, your only option is to upgrade GCC to a known good version.
After CVS update, rebuilding gives the error "No rule to make target".
+After Subversion update, rebuilding gives the error "No rule to make + target".
If the error is of the form:
-+gmake[2]: *** No rule to make target `/path/to/somefile', needed by `/path/to/another/file.d'.-
Stop.
This may occur anytime files are moved within the CVS repository or removed -entirely. In this case, the best solution is to erase all .d files, -which list dependencies for source files, and rebuild:
+This may occur anytime files are moved within the Subversion repository or + removed entirely. In this case, the best solution is to erase all + .d files, which list dependencies for source files, and rebuild:
-+% cd $LLVM_OBJ_DIR % rm -f `find . -name \*\.d` % gmake-
In other cases, it may be necessary to run make clean before -rebuilding.
+ rebuilding. ++ Source Languages +
- -LLVM currently has full support for C and C++ source languages. These are - available through a special version of GCC that LLVM calls the - C Front End
-There is an incomplete version of a Java front end available in the - llvm-java CVS repository. There is no documentation on this yet so - you'll need to download the code, compile it, and try it.
-In the examples/BFtoLLVM directory is a translator for the - BrainF*** language (2002 Language Specification).
-In the projects/Stacker directory is a compiler and runtime - library for the Stacker language, a "toy" language loosely based on Forth.
-The PyPy developers are working on integrating LLVM into the PyPy backend - so that PyPy language can translate to LLVM.
-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 mostly - implemented configuration-driven - compiler driver which simplifies the task - of running optimizations, linking, and executable generation.
-I don't understand the GetElementPtr - instruction. Help!
+ + +LLVM currently has full support for C and C++ source languages. These are + available through both Clang and + DragonEgg.
- -The PyPy developers are working on integrating LLVM into the PyPy backend so + that PyPy language can translate to LLVM.
-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? -
+-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." -
--To work around this, perform the following steps: -
--
-
- Make sure the CC and CXX environment variables contains the full path to - the LLVM GCC front end. +
- Make sure that the regular C compiler is first in your PATH. +
- Call into the LLVM libraries code using your language's FFI + (foreign function interface). -
- Add the string "-Wl,-native" to your CFLAGS environment variable. -
Your compiler front-end will communicate with LLVM by creating a module in + the LLVM intermediate representation (IR) format. Assuming you want to write + your language's compiler in the language itself (rather than C++), there are + 3 major ways to tackle generating LLVM IR from a front-end:
--
+
-
+
- for: best tracks changes to the LLVM IR, .ll syntax, and .bc + format + +
- for: enables running LLVM optimization passes without a + emit/parse overhead + +
- for: adapts well to a JIT context + +
- against: lots of ugly glue code to write +
-
+
- for: very straightforward to get started + +
- against: the .ll parser is slower than the bitcode reader + when interfacing to the middle end -
- against: you'll have to re-engineer the LLVM IR object model + and asm writer in your language + +
- against: it may be harder to track changes to the IR +
-This will allow the llvm-ld 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.
+-
+
- for: can use the more-efficient bitcode reader when + interfacing to the middle end + +
- against: you'll have to re-engineer the LLVM IR object + model and bitcode writer in your language + +
- against: it may be harder to track changes to the IR +
If you go with the first option, the C bindings in include/llvm-c should help + a lot, since most languages have strong support for interfacing with C. The + most common hurdle with calling C from managed code is interfacing with the + garbage collector. The C interface was designed to require very little memory + management, and so is straightforward in this regard.
-When I compile code using the LLVM GCC front end, it complains that it cannot -find libcrtend.a. -
+What support is there for a higher level source language + constructs for building a compiler?
-The only way this can happen is if you haven't installed the runtime library. To -correct this, do:
- --% cd llvm/runtime -% make clean ; make install-bytecode --
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.
-How can I disable all optimizations when compiling code using the LLVM GCC front end? -
+-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. -
+ ++ Using the C and C++ Front Ends +
+ +-Can I use LLVM to convert C++ code to C code? -
+Can I compile C or C++ code to + platform-independent LLVM bitcode?
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. -
+No. C and C++ are inherently platform-dependent languages. The most obvious + example of this is the preprocessor. A very common way that C code is made + 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 + targeting.
-Use commands like this:
+Another example is sizeof. It's common for sizeof(long) to + vary between platforms. In most C front-ends, sizeof is expanded to + a constant immediately, thus hard-wiring a platform-specific detail.
--
-
Compile your program as normal with llvm-g++:
-
-Convert the LLVM code to C code, using the LLC tool with the C -backend:
-
-Finally, compile the c file:
+
-% llvm-g++ x.cpp -o program -+
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.
or:
- --% llvm-g++ a.cpp -c -% llvm-g++ b.cpp -c -% llvm-g++ a.o b.o -o program -
With llvm-gcc3, this will generate program and program.bc. The .bc file is -the LLVM version of the program all linked together.
- --% llc -march=c program.bc -o program.c --
+ Questions about code generated by the demo page +
--% cc x.c -+ - +
If you #include the <iostream> header into a C++ + translation unit, the file will probably use + the std::cin/std::cout/... 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 std::cout, for example, the object would not necessarily be + automatically initialized before your use.
-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. +
To make std::cout 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 <iostream>. 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.
-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 bytecode, 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.
- +If you would like to make it easier to understand the LLVM code + generated by the compiler in the demo page, consider using printf() + instead of iostreams to print values.
-The __main 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. -
+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.
--The actual implementation of __main lives in the -llvm/runtime/GCCLibraries/crtend/ directory in the source-base, and is -linked in automatically when you link the program. -
+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 volatile global + variables.
What is this llvm.global_ctors and -_GLOBAL__I__tmp_webcompile... stuff that happens when I #include -<iostream>?
+undef 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:
-If you #include the <iostream> header into a C++ translation unit, the -file will probably use the std::cin/std::cout/... 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 std::cout, for example, the object would not necessarily -be automatically initialized before your use.
- -To make std::cout 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 <iostream>. 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. -
- -If you would like to make it easier to understand the LLVM code -generated by the compiler in the demo page, consider using printf() -instead of iostreams to print values.
+
+int X() { int i; return i; }
+
+Is compiled to "ret i32 undef" because "i" never has a + value specified for it.
-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. -
+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:
+ +
+define fastcc void @foo() {
+ ret void
+}
+define void @bar() {
+ call void @foo()
+ ret void
+}
+
+
+Is optimized to:
--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 volatile global variables. +
+define fastcc void @foo() {
+ ret void
+}
+define void @bar() {
+ unreachable
+}
+
+
+... 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.
+ +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:
+ +
+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
+}
+
+
+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):
-
+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
+}
+
-
+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: +
--undef 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:
+
+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
+}
+
-
-int X() { int i; return i; }
+The interesting thing about this is that %X must 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:
+
+
+define fastcc void @foo() {
+ ret void
+}
+define void @test(i1 %X) {
+F.i:
+ call fastcc void @foo()
+ ret void
+}
+
Is compiled to "ret i32 undef" because "i" never has -a value specified for it.
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS">
+ LLVM Compiler Infrastructure
Last modified: $Date$