3 ================================
4 Frequently Asked Questions (FAQ)
5 ================================
14 Does the University of Illinois Open Source License really qualify as an "open source" license?
15 -----------------------------------------------------------------------------------------------
16 Yes, the license is `certified
17 <http://www.opensource.org/licenses/UoI-NCSA.php>`_ by the Open Source
21 Can I modify LLVM source code and redistribute the modified source?
22 -------------------------------------------------------------------
23 Yes. The modified source distribution must retain the copyright notice and
24 follow the three bulletted conditions listed in the `LLVM license
25 <http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT>`_.
28 Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?
29 --------------------------------------------------------------------------------------------------------------------------
30 Yes. This is why we distribute LLVM under a less restrictive license than GPL,
31 as explained in the first question above.
37 In what language is LLVM written?
38 ---------------------------------
39 All of the LLVM tools and libraries are written in C++ with extensive use of
43 How portable is the LLVM source code?
44 -------------------------------------
45 The LLVM source code should be portable to most modern Unix-like operating
46 systems. Most of the code is written in standard C++ with operating system
47 services abstracted to a support library. The tools required to build and
48 test LLVM have been ported to a plethora of platforms.
50 Some porting problems may exist in the following areas:
52 * The autoconf/makefile build system relies heavily on UNIX shell tools,
53 like the Bourne Shell and sed. Porting to systems without these tools
54 (MacOS 9, Plan 9) will require more effort.
60 When I run configure, it finds the wrong C compiler.
61 ----------------------------------------------------
62 The ``configure`` script attempts to locate first ``gcc`` and then ``cc``,
63 unless it finds compiler paths set in ``CC`` and ``CXX`` for the C and C++
64 compiler, respectively.
66 If ``configure`` finds the wrong compiler, either adjust your ``PATH``
67 environment variable or set ``CC`` and ``CXX`` explicitly.
70 The ``configure`` script finds the right C compiler, but it uses the LLVM tools from a previous build. What do I do?
71 ---------------------------------------------------------------------------------------------------------------------
72 The ``configure`` script uses the ``PATH`` to find executables, so if it's
73 grabbing the wrong linker/assembler/etc, there are two ways to fix it:
75 #. Adjust your ``PATH`` environment variable so that the correct program
76 appears first in the ``PATH``. This may work, but may not be convenient
77 when you want them *first* in your path for other work.
79 #. Run ``configure`` with an alternative ``PATH`` that is correct. In a
80 Bourne compatible shell, the syntax would be:
84 % PATH=[the path without the bad program] ./configure ...
86 This is still somewhat inconvenient, but it allows ``configure`` to do its
87 work without having to adjust your ``PATH`` permanently.
90 When creating a dynamic library, I get a strange GLIBC error.
91 -------------------------------------------------------------
92 Under some operating systems (i.e. Linux), libtool does not work correctly if
93 GCC was compiled with the ``--disable-shared option``. To work around this,
94 install your own version of GCC that has shared libraries enabled by default.
97 I've updated my source tree from Subversion, and now my build is trying to use a file/directory that doesn't exist.
98 -------------------------------------------------------------------------------------------------------------------
99 You need to re-run configure in your object directory. When new Makefiles
100 are added to the source tree, they have to be copied over to the object tree
101 in order to be used by the build.
104 I've modified a Makefile in my source tree, but my build tree keeps using the old version. What do I do?
105 ---------------------------------------------------------------------------------------------------------
106 If the Makefile already exists in your object tree, you can just run the
107 following command in the top level directory of your object tree:
111 % ./config.status <relative path to Makefile>;
113 If the Makefile is new, you will have to modify the configure script to copy
117 I've upgraded to a new version of LLVM, and I get strange build errors.
118 -----------------------------------------------------------------------
119 Sometimes, changes to the LLVM source code alters how the build system works.
120 Changes in ``libtool``, ``autoconf``, or header file dependencies are
121 especially prone to this sort of problem.
123 The best thing to try is to remove the old files and re-build. In most cases,
124 this takes care of the problem. To do this, just type ``make clean`` and then
125 ``make`` in the directory that fails to build.
128 I've built LLVM and am testing it, but the tests freeze.
129 --------------------------------------------------------
130 This is most likely occurring because you built a profile or release
131 (optimized) build of LLVM and have not specified the same information on the
132 ``gmake`` command line.
134 For example, if you built LLVM with the command:
138 % gmake ENABLE_PROFILING=1
140 ...then you must run the tests with the following commands:
145 % gmake ENABLE_PROFILING=1
147 Why do test results differ when I perform different types of builds?
148 --------------------------------------------------------------------
149 The LLVM test suite is dependent upon several features of the LLVM tools and
152 First, the debugging assertions in code are not enabled in optimized or
153 profiling builds. Hence, tests that used to fail may pass.
155 Second, some tests may rely upon debugging options or behavior that is only
156 available in the debug build. These tests will fail in an optimized or
160 Compiling LLVM with GCC 3.3.2 fails, what should I do?
161 ------------------------------------------------------
162 This is `a bug in GCC <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392>`_,
163 and affects projects other than LLVM. Try upgrading or downgrading your GCC.
166 Compiling LLVM with GCC succeeds, but the resulting tools do not work, what can be wrong?
167 -----------------------------------------------------------------------------------------
168 Several versions of GCC have shown a weakness in miscompiling the LLVM
169 codebase. Please consult your compiler version (``gcc --version``) to find
170 out whether it is `broken <GettingStarted.html#brokengcc>`_. If so, your only
171 option is to upgrade GCC to a known good version.
174 After Subversion update, rebuilding gives the error "No rule to make target".
175 -----------------------------------------------------------------------------
176 If the error is of the form:
180 gmake[2]: *** No rule to make target `/path/to/somefile',
181 needed by `/path/to/another/file.d'.
184 This may occur anytime files are moved within the Subversion repository or
185 removed entirely. In this case, the best solution is to erase all ``.d``
186 files, which list dependencies for source files, and rebuild:
191 % rm -f `find . -name \*\.d`
194 In other cases, it may be necessary to run ``make clean`` before rebuilding.
200 What source languages are supported?
201 ------------------------------------
202 LLVM currently has full support for C and C++ source languages. These are
203 available through both `Clang <http://clang.llvm.org/>`_ and `DragonEgg
204 <http://dragonegg.llvm.org/>`_.
206 The PyPy developers are working on integrating LLVM into the PyPy backend so
207 that PyPy language can translate to LLVM.
210 I'd like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?
211 ----------------------------------------------------------------------------------------------------------------------------------------
212 Your compiler front-end will communicate with LLVM by creating a module in the
213 LLVM intermediate representation (IR) format. Assuming you want to write your
214 language's compiler in the language itself (rather than C++), there are 3
215 major ways to tackle generating LLVM IR from a front-end:
217 1. **Call into the LLVM libraries code using your language's FFI (foreign
218 function interface).**
220 * *for:* best tracks changes to the LLVM IR, .ll syntax, and .bc format
222 * *for:* enables running LLVM optimization passes without a emit/parse
225 * *for:* adapts well to a JIT context
227 * *against:* lots of ugly glue code to write
229 2. **Emit LLVM assembly from your compiler's native language.**
231 * *for:* very straightforward to get started
233 * *against:* the .ll parser is slower than the bitcode reader when
234 interfacing to the middle end
236 * *against:* it may be harder to track changes to the IR
238 3. **Emit LLVM bitcode from your compiler's native language.**
240 * *for:* can use the more-efficient bitcode reader when interfacing to the
243 * *against:* you'll have to re-engineer the LLVM IR object model and bitcode
244 writer in your language
246 * *against:* it may be harder to track changes to the IR
248 If you go with the first option, the C bindings in include/llvm-c should help
249 a lot, since most languages have strong support for interfacing with C. The
250 most common hurdle with calling C from managed code is interfacing with the
251 garbage collector. The C interface was designed to require very little memory
252 management, and so is straightforward in this regard.
254 What support is there for a higher level source language constructs for building a compiler?
255 --------------------------------------------------------------------------------------------
256 Currently, there isn't much. LLVM supports an intermediate representation
257 which is useful for code representation but will not support the high level
258 (abstract syntax tree) representation needed by most compilers. There are no
259 facilities for lexical nor semantic analysis.
262 I don't understand the ``GetElementPtr`` instruction. Help!
263 -----------------------------------------------------------
264 See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_.
267 Using the C and C++ Front Ends
268 ==============================
270 Can I compile C or C++ code to platform-independent LLVM bitcode?
271 -----------------------------------------------------------------
272 No. C and C++ are inherently platform-dependent languages. The most obvious
273 example of this is the preprocessor. A very common way that C code is made
274 portable is by using the preprocessor to include platform-specific code. In
275 practice, information about other platforms is lost after preprocessing, so
276 the result is inherently dependent on the platform that the preprocessing was
279 Another example is ``sizeof``. It's common for ``sizeof(long)`` to vary
280 between platforms. In most C front-ends, ``sizeof`` is expanded to a
281 constant immediately, thus hard-wiring a platform-specific detail.
283 Also, since many platforms define their ABIs in terms of C, and since LLVM is
284 lower-level than C, front-ends currently must emit platform-specific IR in
285 order to have the result conform to the platform ABI.
288 Questions about code generated by the demo page
289 ===============================================
291 What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``?
292 -------------------------------------------------------------------------------------------------------------
293 If you ``#include`` the ``<iostream>`` header into a C++ translation unit,
294 the file will probably use the ``std::cin``/``std::cout``/... global objects.
295 However, C++ does not guarantee an order of initialization between static
296 objects in different translation units, so if a static ctor/dtor in your .cpp
297 file used ``std::cout``, for example, the object would not necessarily be
298 automatically initialized before your use.
300 To make ``std::cout`` and friends work correctly in these scenarios, the STL
301 that we use declares a static object that gets created in every translation
302 unit that includes ``<iostream>``. This object has a static constructor
303 and destructor that initializes and destroys the global iostream objects
304 before they could possibly be used in the file. The code that you see in the
305 ``.ll`` file corresponds to the constructor and destructor registration code.
307 If you would like to make it easier to *understand* the LLVM code generated
308 by the compiler in the demo page, consider using ``printf()`` instead of
309 ``iostream``\s to print values.
312 Where did all of my code go??
313 -----------------------------
314 If you are using the LLVM demo page, you may often wonder what happened to
315 all of the code that you typed in. Remember that the demo script is running
316 the code through the LLVM optimizers, so if your code doesn't actually do
317 anything useful, it might all be deleted.
319 To prevent this, make sure that the code is actually needed. For example, if
320 you are computing some expression, return the value from the function instead
321 of leaving it in a local variable. If you really want to constrain the
322 optimizer, you can read from and assign to ``volatile`` global variables.
325 What is this "``undef``" thing that shows up in my code?
326 --------------------------------------------------------
327 ``undef`` is the LLVM way of representing a value that is not defined. You
328 can get these if you do not initialize a variable before you use it. For
329 example, the C function:
333 int X() { int i; return i; }
335 Is compiled to "``ret i32 undef``" because "``i``" never has a value specified
339 Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into "unreachable"? Why not make the verifier reject it?
340 ----------------------------------------------------------------------------------------------------------------------------------------------------------
341 This is a common problem run into by authors of front-ends that are using
342 custom calling conventions: you need to make sure to set the right calling
343 convention on both the function and on each call to the function. For
348 define fastcc void @foo() {
360 define fastcc void @foo() {
367 ... with "``opt -instcombine -simplifycfg``". This often bites people because
368 "all their code disappears". Setting the calling convention on the caller and
369 callee is required for indirect calls to work, so people often ask why not
370 make the verifier reject this sort of thing.
372 The answer is that this code has undefined behavior, but it is not illegal.
373 If we made it illegal, then every transformation that could potentially create
374 this would have to ensure that it doesn't, and there is valid code that can
375 create this sort of construct (in dead code). The sorts of things that can
376 cause this to happen are fairly contrived, but we still need to accept them.
381 define fastcc void @foo() {
384 define internal void @bar(void()* %FP, i1 %cond) {
385 br i1 %cond, label %T, label %F
390 call fastcc void %FP()
393 define void @test() {
394 %X = or i1 false, false
395 call void @bar(void()* @foo, i1 %X)
399 In this example, "test" always passes ``@foo``/``false`` into ``bar``, which
400 ensures that it is dynamically called with the right calling conv (thus, the
401 code is perfectly well defined). If you run this through the inliner, you
402 get this (the explicit "or" is there so that the inliner doesn't dead code
403 eliminate a bunch of stuff):
407 define fastcc void @foo() {
410 define void @test() {
411 %X = or i1 false, false
412 br i1 %X, label %T.i, label %F.i
417 call fastcc void @foo()
423 Here you can see that the inlining pass made an undefined call to ``@foo``
424 with the wrong calling convention. We really don't want to make the inliner
425 have to know about this sort of thing, so it needs to be valid code. In this
426 case, dead code elimination can trivially remove the undefined code. However,
427 if ``%X`` was an input argument to ``@test``, the inliner would produce this:
431 define fastcc void @foo() {
435 define void @test(i1 %X) {
436 br i1 %X, label %T.i, label %F.i
441 call fastcc void @foo()
447 The interesting thing about this is that ``%X`` *must* be false for the
448 code to be well-defined, but no amount of dead code elimination will be able
449 to delete the broken call as unreachable. However, since
450 ``instcombine``/``simplifycfg`` turns the undefined call into unreachable, we
451 end up with a branch on a condition that goes to unreachable: a branch to
452 unreachable can never happen, so "``-inline -instcombine -simplifycfg``" is
457 define fastcc void @foo() {
460 define void @test(i1 %X) {
462 call fastcc void @foo()