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] $LLVM_SRC_DIR/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 187After Subversion update, rebuilding gives the error "No rule to make target". 188----------------------------------------------------------------------------- 189If the error is of the form: 190 191.. code-block:: console 192 193 gmake[2]: *** No rule to make target `/path/to/somefile', 194 needed by `/path/to/another/file.d'. 195 Stop. 196 197This may occur anytime files are moved within the Subversion repository or 198removed entirely. In this case, the best solution is to erase all ``.d`` 199files, which list dependencies for source files, and rebuild: 200 201.. code-block:: console 202 203 % cd $LLVM_OBJ_DIR 204 % rm -f `find . -name \*\.d` 205 % gmake 206 207In other cases, it may be necessary to run ``make clean`` before rebuilding. 208 209 210Source Languages 211================ 212 213What source languages are supported? 214------------------------------------ 215LLVM currently has full support for C and C++ source languages. These are 216available through both `Clang <http://clang.llvm.org/>`_ and `DragonEgg 217<http://dragonegg.llvm.org/>`_. 218 219The PyPy developers are working on integrating LLVM into the PyPy backend so 220that PyPy language can translate to LLVM. 221 222 223I'd like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators? 224---------------------------------------------------------------------------------------------------------------------------------------- 225Your compiler front-end will communicate with LLVM by creating a module in the 226LLVM intermediate representation (IR) format. Assuming you want to write your 227language's compiler in the language itself (rather than C++), there are 3 228major ways to tackle generating LLVM IR from a front-end: 229 2301. **Call into the LLVM libraries code using your language's FFI (foreign 231 function interface).** 232 233 * *for:* best tracks changes to the LLVM IR, .ll syntax, and .bc format 234 235 * *for:* enables running LLVM optimization passes without a emit/parse 236 overhead 237 238 * *for:* adapts well to a JIT context 239 240 * *against:* lots of ugly glue code to write 241 2422. **Emit LLVM assembly from your compiler's native language.** 243 244 * *for:* very straightforward to get started 245 246 * *against:* the .ll parser is slower than the bitcode reader when 247 interfacing to the middle end 248 249 * *against:* it may be harder to track changes to the IR 250 2513. **Emit LLVM bitcode from your compiler's native language.** 252 253 * *for:* can use the more-efficient bitcode reader when interfacing to the 254 middle end 255 256 * *against:* you'll have to re-engineer the LLVM IR object model and bitcode 257 writer in your language 258 259 * *against:* it may be harder to track changes to the IR 260 261If you go with the first option, the C bindings in include/llvm-c should help 262a lot, since most languages have strong support for interfacing with C. The 263most common hurdle with calling C from managed code is interfacing with the 264garbage collector. The C interface was designed to require very little memory 265management, and so is straightforward in this regard. 266 267What support is there for a higher level source language constructs for building a compiler? 268-------------------------------------------------------------------------------------------- 269Currently, there isn't much. LLVM supports an intermediate representation 270which is useful for code representation but will not support the high level 271(abstract syntax tree) representation needed by most compilers. There are no 272facilities for lexical nor semantic analysis. 273 274 275I don't understand the ``GetElementPtr`` instruction. Help! 276----------------------------------------------------------- 277See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_. 278 279 280Using the C and C++ Front Ends 281============================== 282 283Can I compile C or C++ code to platform-independent LLVM bitcode? 284----------------------------------------------------------------- 285No. C and C++ are inherently platform-dependent languages. The most obvious 286example of this is the preprocessor. A very common way that C code is made 287portable is by using the preprocessor to include platform-specific code. In 288practice, information about other platforms is lost after preprocessing, so 289the result is inherently dependent on the platform that the preprocessing was 290targeting. 291 292Another example is ``sizeof``. It's common for ``sizeof(long)`` to vary 293between platforms. In most C front-ends, ``sizeof`` is expanded to a 294constant immediately, thus hard-wiring a platform-specific detail. 295 296Also, since many platforms define their ABIs in terms of C, and since LLVM is 297lower-level than C, front-ends currently must emit platform-specific IR in 298order to have the result conform to the platform ABI. 299 300 301Questions about code generated by the demo page 302=============================================== 303 304What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``? 305------------------------------------------------------------------------------------------------------------- 306If you ``#include`` the ``<iostream>`` header into a C++ translation unit, 307the file will probably use the ``std::cin``/``std::cout``/... global objects. 308However, C++ does not guarantee an order of initialization between static 309objects in different translation units, so if a static ctor/dtor in your .cpp 310file used ``std::cout``, for example, the object would not necessarily be 311automatically initialized before your use. 312 313To make ``std::cout`` and friends work correctly in these scenarios, the STL 314that we use declares a static object that gets created in every translation 315unit that includes ``<iostream>``. This object has a static constructor 316and destructor that initializes and destroys the global iostream objects 317before they could possibly be used in the file. The code that you see in the 318``.ll`` file corresponds to the constructor and destructor registration code. 319 320If you would like to make it easier to *understand* the LLVM code generated 321by the compiler in the demo page, consider using ``printf()`` instead of 322``iostream``\s to print values. 323 324 325Where did all of my code go?? 326----------------------------- 327If you are using the LLVM demo page, you may often wonder what happened to 328all of the code that you typed in. Remember that the demo script is running 329the code through the LLVM optimizers, so if your code doesn't actually do 330anything useful, it might all be deleted. 331 332To prevent this, make sure that the code is actually needed. For example, if 333you are computing some expression, return the value from the function instead 334of leaving it in a local variable. If you really want to constrain the 335optimizer, you can read from and assign to ``volatile`` global variables. 336 337 338What is this "``undef``" thing that shows up in my code? 339-------------------------------------------------------- 340``undef`` is the LLVM way of representing a value that is not defined. You 341can get these if you do not initialize a variable before you use it. For 342example, the C function: 343 344.. code-block:: c 345 346 int X() { int i; return i; } 347 348Is compiled to "``ret i32 undef``" because "``i``" never has a value specified 349for it. 350 351 352Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into "unreachable"? Why not make the verifier reject it? 353---------------------------------------------------------------------------------------------------------------------------------------------------------- 354This is a common problem run into by authors of front-ends that are using 355custom calling conventions: you need to make sure to set the right calling 356convention on both the function and on each call to the function. For 357example, this code: 358 359.. code-block:: llvm 360 361 define fastcc void @foo() { 362 ret void 363 } 364 define void @bar() { 365 call void @foo() 366 ret void 367 } 368 369Is optimized to: 370 371.. code-block:: llvm 372 373 define fastcc void @foo() { 374 ret void 375 } 376 define void @bar() { 377 unreachable 378 } 379 380... with "``opt -instcombine -simplifycfg``". This often bites people because 381"all their code disappears". Setting the calling convention on the caller and 382callee is required for indirect calls to work, so people often ask why not 383make the verifier reject this sort of thing. 384 385The answer is that this code has undefined behavior, but it is not illegal. 386If we made it illegal, then every transformation that could potentially create 387this would have to ensure that it doesn't, and there is valid code that can 388create this sort of construct (in dead code). The sorts of things that can 389cause this to happen are fairly contrived, but we still need to accept them. 390Here's an example: 391 392.. code-block:: llvm 393 394 define fastcc void @foo() { 395 ret void 396 } 397 define internal void @bar(void()* %FP, i1 %cond) { 398 br i1 %cond, label %T, label %F 399 T: 400 call void %FP() 401 ret void 402 F: 403 call fastcc void %FP() 404 ret void 405 } 406 define void @test() { 407 %X = or i1 false, false 408 call void @bar(void()* @foo, i1 %X) 409 ret void 410 } 411 412In this example, "test" always passes ``@foo``/``false`` into ``bar``, which 413ensures that it is dynamically called with the right calling conv (thus, the 414code is perfectly well defined). If you run this through the inliner, you 415get this (the explicit "or" is there so that the inliner doesn't dead code 416eliminate a bunch of stuff): 417 418.. code-block:: llvm 419 420 define fastcc void @foo() { 421 ret void 422 } 423 define void @test() { 424 %X = or i1 false, false 425 br i1 %X, label %T.i, label %F.i 426 T.i: 427 call void @foo() 428 br label %bar.exit 429 F.i: 430 call fastcc void @foo() 431 br label %bar.exit 432 bar.exit: 433 ret void 434 } 435 436Here you can see that the inlining pass made an undefined call to ``@foo`` 437with the wrong calling convention. We really don't want to make the inliner 438have to know about this sort of thing, so it needs to be valid code. In this 439case, dead code elimination can trivially remove the undefined code. However, 440if ``%X`` was an input argument to ``@test``, the inliner would produce this: 441 442.. code-block:: llvm 443 444 define fastcc void @foo() { 445 ret void 446 } 447 448 define void @test(i1 %X) { 449 br i1 %X, label %T.i, label %F.i 450 T.i: 451 call void @foo() 452 br label %bar.exit 453 F.i: 454 call fastcc void @foo() 455 br label %bar.exit 456 bar.exit: 457 ret void 458 } 459 460The interesting thing about this is that ``%X`` *must* be false for the 461code to be well-defined, but no amount of dead code elimination will be able 462to delete the broken call as unreachable. However, since 463``instcombine``/``simplifycfg`` turns the undefined call into unreachable, we 464end up with a branch on a condition that goes to unreachable: a branch to 465unreachable can never happen, so "``-inline -instcombine -simplifycfg``" is 466able to produce: 467 468.. code-block:: llvm 469 470 define fastcc void @foo() { 471 ret void 472 } 473 define void @test(i1 %X) { 474 F.i: 475 call fastcc void @foo() 476 ret void 477 } 478