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