1.. _faq: 2 3================================ 4Frequently Asked Questions (FAQ) 5================================ 6 7.. contents:: 8 :local: 9 10 11License 12======= 13 14Does the University of Illinois Open Source License really qualify as an "open source" license? 15----------------------------------------------------------------------------------------------- 16Yes, the license is `certified 17<http://www.opensource.org/licenses/UoI-NCSA.php>`_ by the Open Source 18Initiative (OSI). 19 20 21Can I modify LLVM source code and redistribute the modified source? 22------------------------------------------------------------------- 23Yes. The modified source distribution must retain the copyright notice and 24follow the three bulletted conditions listed in the `LLVM license 25<http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT>`_. 26 27 28Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source? 29-------------------------------------------------------------------------------------------------------------------------- 30Yes. This is why we distribute LLVM under a less restrictive license than GPL, 31as explained in the first question above. 32 33 34Source Code 35=========== 36 37In what language is LLVM written? 38--------------------------------- 39All of the LLVM tools and libraries are written in C++ with extensive use of 40the STL. 41 42 43How portable is the LLVM source code? 44------------------------------------- 45The LLVM source code should be portable to most modern Unix-like operating 46systems. Most of the code is written in standard C++ with operating system 47services abstracted to a support library. The tools required to build and 48test LLVM have been ported to a plethora of platforms. 49 50Some porting problems may exist in the following areas: 51 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. 55 56 57Build Problems 58============== 59 60When I run configure, it finds the wrong C compiler. 61---------------------------------------------------- 62The ``configure`` script attempts to locate first ``gcc`` and then ``cc``, 63unless it finds compiler paths set in ``CC`` and ``CXX`` for the C and C++ 64compiler, respectively. 65 66If ``configure`` finds the wrong compiler, either adjust your ``PATH`` 67environment variable or set ``CC`` and ``CXX`` explicitly. 68 69 70The ``configure`` script finds the right C compiler, but it uses the LLVM tools from a previous build. What do I do? 71--------------------------------------------------------------------------------------------------------------------- 72The ``configure`` script uses the ``PATH`` to find executables, so if it's 73grabbing the wrong linker/assembler/etc, there are two ways to fix it: 74 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. 78 79#. Run ``configure`` with an alternative ``PATH`` that is correct. In a 80 Bourne compatible shell, the syntax would be: 81 82.. code-block:: bash 83 84 % PATH=[the path without the bad program] ./configure ... 85 86This is still somewhat inconvenient, but it allows ``configure`` to do its 87work without having to adjust your ``PATH`` permanently. 88 89 90When creating a dynamic library, I get a strange GLIBC error. 91------------------------------------------------------------- 92Under some operating systems (i.e. Linux), libtool does not work correctly if 93GCC was compiled with the ``--disable-shared option``. To work around this, 94install your own version of GCC that has shared libraries enabled by default. 95 96 97I've updated my source tree from Subversion, and now my build is trying to use a file/directory that doesn't exist. 98------------------------------------------------------------------------------------------------------------------- 99You need to re-run configure in your object directory. When new Makefiles 100are added to the source tree, they have to be copied over to the object tree 101in order to be used by the build. 102 103 104I've modified a Makefile in my source tree, but my build tree keeps using the old version. What do I do? 105--------------------------------------------------------------------------------------------------------- 106If the Makefile already exists in your object tree, you can just run the 107following command in the top level directory of your object tree: 108 109.. code-block:: bash 110 111 % ./config.status <relative path to Makefile>; 112 113If the Makefile is new, you will have to modify the configure script to copy 114it over. 115 116 117I've upgraded to a new version of LLVM, and I get strange build errors. 118----------------------------------------------------------------------- 119Sometimes, changes to the LLVM source code alters how the build system works. 120Changes in ``libtool``, ``autoconf``, or header file dependencies are 121especially prone to this sort of problem. 122 123The best thing to try is to remove the old files and re-build. In most cases, 124this takes care of the problem. To do this, just type ``make clean`` and then 125``make`` in the directory that fails to build. 126 127 128I've built LLVM and am testing it, but the tests freeze. 129-------------------------------------------------------- 130This 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. 133 134For example, if you built LLVM with the command: 135 136.. code-block:: bash 137 138 % gmake ENABLE_PROFILING=1 139 140...then you must run the tests with the following commands: 141 142.. code-block:: bash 143 144 % cd llvm/test 145 % gmake ENABLE_PROFILING=1 146 147Why do test results differ when I perform different types of builds? 148-------------------------------------------------------------------- 149The LLVM test suite is dependent upon several features of the LLVM tools and 150libraries. 151 152First, the debugging assertions in code are not enabled in optimized or 153profiling builds. Hence, tests that used to fail may pass. 154 155Second, some tests may rely upon debugging options or behavior that is only 156available in the debug build. These tests will fail in an optimized or 157profile build. 158 159 160Compiling LLVM with GCC 3.3.2 fails, what should I do? 161------------------------------------------------------ 162This is `a bug in GCC <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392>`_, 163and affects projects other than LLVM. Try upgrading or downgrading your GCC. 164 165 166Compiling LLVM with GCC succeeds, but the resulting tools do not work, what can be wrong? 167----------------------------------------------------------------------------------------- 168Several versions of GCC have shown a weakness in miscompiling the LLVM 169codebase. Please consult your compiler version (``gcc --version``) to find 170out whether it is `broken <GettingStarted.html#brokengcc>`_. If so, your only 171option is to upgrade GCC to a known good version. 172 173 174After Subversion update, rebuilding gives the error "No rule to make target". 175----------------------------------------------------------------------------- 176If the error is of the form: 177 178.. code-block:: bash 179 180 gmake[2]: *** No rule to make target `/path/to/somefile', 181 needed by `/path/to/another/file.d'. 182 Stop. 183 184This may occur anytime files are moved within the Subversion repository or 185removed entirely. In this case, the best solution is to erase all ``.d`` 186files, which list dependencies for source files, and rebuild: 187 188.. code-block:: bash 189 190 % cd $LLVM_OBJ_DIR 191 % rm -f `find . -name \*\.d` 192 % gmake 193 194In other cases, it may be necessary to run ``make clean`` before rebuilding. 195 196 197Source Languages 198================ 199 200What source languages are supported? 201------------------------------------ 202LLVM currently has full support for C and C++ source languages. These are 203available through both `Clang <http://clang.llvm.org/>`_ and `DragonEgg 204<http://dragonegg.llvm.org/>`_. 205 206The PyPy developers are working on integrating LLVM into the PyPy backend so 207that PyPy language can translate to LLVM. 208 209 210I'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---------------------------------------------------------------------------------------------------------------------------------------- 212Your compiler front-end will communicate with LLVM by creating a module in the 213LLVM intermediate representation (IR) format. Assuming you want to write your 214language's compiler in the language itself (rather than C++), there are 3 215major ways to tackle generating LLVM IR from a front-end: 216 2171. **Call into the LLVM libraries code using your language's FFI (foreign 218 function interface).** 219 220 * *for:* best tracks changes to the LLVM IR, .ll syntax, and .bc format 221 222 * *for:* enables running LLVM optimization passes without a emit/parse 223 overhead 224 225 * *for:* adapts well to a JIT context 226 227 * *against:* lots of ugly glue code to write 228 2292. **Emit LLVM assembly from your compiler's native language.** 230 231 * *for:* very straightforward to get started 232 233 * *against:* the .ll parser is slower than the bitcode reader when 234 interfacing to the middle end 235 236 * *against:* it may be harder to track changes to the IR 237 2383. **Emit LLVM bitcode from your compiler's native language.** 239 240 * *for:* can use the more-efficient bitcode reader when interfacing to the 241 middle end 242 243 * *against:* you'll have to re-engineer the LLVM IR object model and bitcode 244 writer in your language 245 246 * *against:* it may be harder to track changes to the IR 247 248If you go with the first option, the C bindings in include/llvm-c should help 249a lot, since most languages have strong support for interfacing with C. The 250most common hurdle with calling C from managed code is interfacing with the 251garbage collector. The C interface was designed to require very little memory 252management, and so is straightforward in this regard. 253 254What support is there for a higher level source language constructs for building a compiler? 255-------------------------------------------------------------------------------------------- 256Currently, there isn't much. LLVM supports an intermediate representation 257which is useful for code representation but will not support the high level 258(abstract syntax tree) representation needed by most compilers. There are no 259facilities for lexical nor semantic analysis. 260 261 262I don't understand the ``GetElementPtr`` instruction. Help! 263----------------------------------------------------------- 264See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_. 265 266 267Using the C and C++ Front Ends 268============================== 269 270Can I compile C or C++ code to platform-independent LLVM bitcode? 271----------------------------------------------------------------- 272No. C and C++ are inherently platform-dependent languages. The most obvious 273example of this is the preprocessor. A very common way that C code is made 274portable is by using the preprocessor to include platform-specific code. In 275practice, information about other platforms is lost after preprocessing, so 276the result is inherently dependent on the platform that the preprocessing was 277targeting. 278 279Another example is ``sizeof``. It's common for ``sizeof(long)`` to vary 280between platforms. In most C front-ends, ``sizeof`` is expanded to a 281constant immediately, thus hard-wiring a platform-specific detail. 282 283Also, since many platforms define their ABIs in terms of C, and since LLVM is 284lower-level than C, front-ends currently must emit platform-specific IR in 285order to have the result conform to the platform ABI. 286 287 288Questions about code generated by the demo page 289=============================================== 290 291What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``? 292------------------------------------------------------------------------------------------------------------- 293If you ``#include`` the ``<iostream>`` header into a C++ translation unit, 294the file will probably use the ``std::cin``/``std::cout``/... global objects. 295However, C++ does not guarantee an order of initialization between static 296objects in different translation units, so if a static ctor/dtor in your .cpp 297file used ``std::cout``, for example, the object would not necessarily be 298automatically initialized before your use. 299 300To make ``std::cout`` and friends work correctly in these scenarios, the STL 301that we use declares a static object that gets created in every translation 302unit that includes ``<iostream>``. This object has a static constructor 303and destructor that initializes and destroys the global iostream objects 304before 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. 306 307If you would like to make it easier to *understand* the LLVM code generated 308by the compiler in the demo page, consider using ``printf()`` instead of 309``iostream``\s to print values. 310 311 312Where did all of my code go?? 313----------------------------- 314If you are using the LLVM demo page, you may often wonder what happened to 315all of the code that you typed in. Remember that the demo script is running 316the code through the LLVM optimizers, so if your code doesn't actually do 317anything useful, it might all be deleted. 318 319To prevent this, make sure that the code is actually needed. For example, if 320you are computing some expression, return the value from the function instead 321of leaving it in a local variable. If you really want to constrain the 322optimizer, you can read from and assign to ``volatile`` global variables. 323 324 325What 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 328can get these if you do not initialize a variable before you use it. For 329example, the C function: 330 331.. code-block:: c 332 333 int X() { int i; return i; } 334 335Is compiled to "``ret i32 undef``" because "``i``" never has a value specified 336for it. 337 338 339Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into "unreachable"? Why not make the verifier reject it? 340---------------------------------------------------------------------------------------------------------------------------------------------------------- 341This is a common problem run into by authors of front-ends that are using 342custom calling conventions: you need to make sure to set the right calling 343convention on both the function and on each call to the function. For 344example, this code: 345 346.. code-block:: llvm 347 348 define fastcc void @foo() { 349 ret void 350 } 351 define void @bar() { 352 call void @foo() 353 ret void 354 } 355 356Is optimized to: 357 358.. code-block:: llvm 359 360 define fastcc void @foo() { 361 ret void 362 } 363 define void @bar() { 364 unreachable 365 } 366 367... with "``opt -instcombine -simplifycfg``". This often bites people because 368"all their code disappears". Setting the calling convention on the caller and 369callee is required for indirect calls to work, so people often ask why not 370make the verifier reject this sort of thing. 371 372The answer is that this code has undefined behavior, but it is not illegal. 373If we made it illegal, then every transformation that could potentially create 374this would have to ensure that it doesn't, and there is valid code that can 375create this sort of construct (in dead code). The sorts of things that can 376cause this to happen are fairly contrived, but we still need to accept them. 377Here's an example: 378 379.. code-block:: llvm 380 381 define fastcc void @foo() { 382 ret void 383 } 384 define internal void @bar(void()* %FP, i1 %cond) { 385 br i1 %cond, label %T, label %F 386 T: 387 call void %FP() 388 ret void 389 F: 390 call fastcc void %FP() 391 ret void 392 } 393 define void @test() { 394 %X = or i1 false, false 395 call void @bar(void()* @foo, i1 %X) 396 ret void 397 } 398 399In this example, "test" always passes ``@foo``/``false`` into ``bar``, which 400ensures that it is dynamically called with the right calling conv (thus, the 401code is perfectly well defined). If you run this through the inliner, you 402get this (the explicit "or" is there so that the inliner doesn't dead code 403eliminate a bunch of stuff): 404 405.. code-block:: llvm 406 407 define fastcc void @foo() { 408 ret void 409 } 410 define void @test() { 411 %X = or i1 false, false 412 br i1 %X, label %T.i, label %F.i 413 T.i: 414 call void @foo() 415 br label %bar.exit 416 F.i: 417 call fastcc void @foo() 418 br label %bar.exit 419 bar.exit: 420 ret void 421 } 422 423Here you can see that the inlining pass made an undefined call to ``@foo`` 424with the wrong calling convention. We really don't want to make the inliner 425have to know about this sort of thing, so it needs to be valid code. In this 426case, dead code elimination can trivially remove the undefined code. However, 427if ``%X`` was an input argument to ``@test``, the inliner would produce this: 428 429.. code-block:: llvm 430 431 define fastcc void @foo() { 432 ret void 433 } 434 435 define void @test(i1 %X) { 436 br i1 %X, label %T.i, label %F.i 437 T.i: 438 call void @foo() 439 br label %bar.exit 440 F.i: 441 call fastcc void @foo() 442 br label %bar.exit 443 bar.exit: 444 ret void 445 } 446 447The interesting thing about this is that ``%X`` *must* be false for the 448code to be well-defined, but no amount of dead code elimination will be able 449to delete the broken call as unreachable. However, since 450``instcombine``/``simplifycfg`` turns the undefined call into unreachable, we 451end up with a branch on a condition that goes to unreachable: a branch to 452unreachable can never happen, so "``-inline -instcombine -simplifycfg``" is 453able to produce: 454 455.. code-block:: llvm 456 457 define fastcc void @foo() { 458 ret void 459 } 460 define void @test(i1 %X) { 461 F.i: 462 call fastcc void @foo() 463 ret void 464 } 465