docs/FAQ.rst

   1 .. _faq:
   2
   3 ================================
   4 Frequently Asked Questions (FAQ)
   5 ================================
   6
   7 .. contents::
   8    :local:
   9
  10
  11 License
  12 =======
  13
  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
  18 Initiative (OSI).
  19
  20
  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>`_.
  26
  27
  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.
  32
  33
  34 Source Code
  35 ===========
  36
  37 In what language is LLVM written?
  38 ---------------------------------
  39 All of the LLVM tools and libraries are written in C++ with extensive use of
  40 the STL.
  41
  42
  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.
  49
  50 Some 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
  57 Build Problems
  58 ==============
  59
  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.
  65
  66 If ``configure`` finds the wrong compiler, either adjust your ``PATH``
  67 environment variable or set ``CC`` and ``CXX`` explicitly.
  68
  69
  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:
  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
  86 This is still somewhat inconvenient, but it allows ``configure`` to do its
  87 work without having to adjust your ``PATH`` permanently.
  88
  89
  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.
  95
  96
  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.
 102
 103
 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:
 108
 109 .. code-block:: bash
 110
 111    % ./config.status <relative path to Makefile>;
 112
 113 If the Makefile is new, you will have to modify the configure script to copy
 114 it over.
 115
 116
 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.
 122
 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.
 126
 127
 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.
 133
 134 For 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
 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
 150 libraries.
 151
 152 First, the debugging assertions in code are not enabled in optimized or
 153 profiling builds.  Hence, tests that used to fail may pass.
 154
 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
 157 profile build.
 158
 159
 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.
 164
 165
 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.
 172
 173
 174 After Subversion update, rebuilding gives the error "No rule to make target".
 175 -----------------------------------------------------------------------------
 176 If 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
 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:
 187
 188 .. code-block:: bash
 189
 190    % cd $LLVM_OBJ_DIR
 191    % rm -f `find . -name \*\.d`
 192    % gmake
 193
 194 In other cases, it may be necessary to run ``make clean`` before rebuilding.
 195
 196
 197 Source Languages
 198 ================
 199
 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/>`_.
 205
 206 The PyPy developers are working on integrating LLVM into the PyPy backend so
 207 that PyPy language can translate to LLVM.
 208
 209
 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:
 216
 217 1. **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
 229 2. **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
 238 3. **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
 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.
 253
 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.
 260
 261
 262 I don't understand the ``GetElementPtr`` instruction. Help!
 263 -----------------------------------------------------------
 264 See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_.
 265
 266
 267 Using the C and C++ Front Ends
 268 ==============================
 269
 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
 277 targeting.
 278
 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.
 282
 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.
 286
 287
 288 Questions about code generated by the demo page
 289 ===============================================
 290
 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.
 299
 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.
 306
 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.
 310
 311
 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.
 318
 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.
 323
 324
 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:
 330
 331 .. code-block:: c
 332
 333    int X() { int i; return i; }
 334
 335 Is compiled to "``ret i32 undef``" because "``i``" never has a value specified
 336 for it.
 337
 338
 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
 344 example, 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
 356 Is 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
 369 callee is required for indirect calls to work, so people often ask why not
 370 make the verifier reject this sort of thing.
 371
 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.
 377 Here'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
 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):
 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
 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:
 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
 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
 453 able 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    }