docs/FAQ.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <title>LLVM: Frequently Asked Questions</title>
   6   <style type="text/css">
   7     @import url("llvm.css");
   8     .question { font-weight: bold }
   9     .answer   { margin-left: 2em  }
  10   </style>
  11 </head>
  12 <body>
  13
  14 <div class="doc_title">
  15   LLVM: Frequently Asked Questions
  16 </div>
  17
  18 <ol>
  19   <li><a href="#license">License</a>
  20   <ol>
  21   <li>Why are the LLVM source code and the front-end distributed under different
  22   licenses?</li>
  23   <li>Does the University of Illinois Open Source License really qualify as an
  24   "open source" license?</li>
  25   <li>Can I modify LLVM source code and redistribute the modified source?</li>
  26   <li>Can I modify LLVM source code and redistribute binaries or other tools
  27   based on it, without redistributing the source?</li>
  28   </ol></li>
  29
  30   <li><a href="#source">Source code</a>
  31   <ol>
  32   <li>In what language is LLVM written?</li>
  33   <li>How portable is the LLVM source code?</li>
  34   </ol></li>
  35
  36   <li><a href="#build">Build Problems</a>
  37   <ol>
  38   <li>When I run configure, it finds the wrong C compiler.</li>
  39   <li>I compile the code, and I get some error about <tt>/localhome</tt>.</li>
  40   <li>The <tt>configure</tt> script finds the right C compiler, but it uses the
  41   LLVM linker from a previous build.  What do I do?</li>
  42   <li>When creating a dynamic library, I get a strange GLIBC error.</li>
  43   <li>I've updated my source tree from CVS, and now my build is trying to use a
  44   file/directory that doesn't exist.</li>
  45   <li>I've modified a Makefile in my source tree, but my build tree keeps using
  46   the old version.  What do I do?</li>
  47   <li>I've upgraded to a new version of LLVM, and I get strange build
  48   errors.</li>
  49   <li>I've built LLVM and am testing it, but the tests freeze.</li>
  50   <li>Why do test results differ when I perform different types of builds?</li>
  51   <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
  52   <li>When I use the test suite, all of the C Backend tests fail.  What is
  53       wrong?</li>
  54   <li>After CVS update, rebuilding gives the error "No rule to make
  55   target".</li>
  56   </ol></li>
  57
  58   <li><a href="#cfe">Using the GCC Front End</a>
  59   <ol>
  60     <li>
  61     When I compile software that uses a configure script, the configure script
  62     thinks my system has all of the header files and libraries it is testing
  63     for.  How do I get configure to work correctly?
  64     </li>
  65
  66     <li>
  67     When I compile code using the LLVM GCC front end, it complains that it
  68     cannot find libcrtend.a.
  69     </li>
  70   </ol>
  71   </li>
  72
  73   <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
  74   <ol>
  75      <li>What is this <tt>__main()</tt> call that gets inserted into
  76          <tt>main()</tt>?</li>
  77      <li>Where did all of my code go??</li>
  78      <li>What is this <tt>llvm.global_ctors</tt> and
  79           <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
  80           #include &lt;iostream&gt;?</li>
  81   </ol>
  82   </li>
  83 </ol>
  84
  85 <div class="doc_author">
  86   <p>Written by <a href="http://llvm.cs.uiuc.edu">The LLVM Team</a></p>
  87 </div>
  88
  89
  90 <!-- *********************************************************************** -->
  91 <div class="doc_section">
  92   <a name="license">License</a>
  93 </div>
  94 <!-- *********************************************************************** -->
  95
  96 <div class="question">
  97 <p>Why are the LLVM source code and the front-end distributed under different
  98 licenses?</p>
  99 </div>
 100
 101 <div class="answer">
 102 <p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
 103 Our aim is to distribute LLVM source code under a <em>much less restrictive</em>
 104 license, in particular one that does not compel users who distribute tools based
 105 on modifying the source to redistribute the modified source code as well.</p>
 106 </div>
 107
 108 <div class="question">
 109 <p>Does the University of Illinois Open Source License really qualify as an
 110 "open source" license?</p>
 111 </div>
 112
 113 <div class="answer">
 114 <p>Yes, the license is <a
 115 href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open
 116 Source Initiative (OSI).</p>
 117 </div>
 118
 119 <div class="question">
 120 <p>Can I modify LLVM source code and redistribute the modified source?</p>
 121 </div>
 122
 123 <div class="answer">
 124 <p>Yes.  The modified source distribution must retain the copyright notice and
 125 follow the three bulletted conditions listed in the <a
 126 href="http://llvm.cs.uiuc.edu/releases/1.2/LICENSE.TXT">LLVM license</a>.</p>
 127 </div>
 128
 129 <div class="question">
 130 <p>Can I modify LLVM source code and redistribute binaries or other tools based
 131 on it, without redistributing the source?</p>
 132 </div>
 133
 134 <div class="answer">
 135 <p>Yes, this is why we distribute LLVM under a less restrictive license than
 136 GPL, as explained in the first question above.</p>
 137 </div>
 138
 139 <!-- *********************************************************************** -->
 140 <div class="doc_section">
 141   <a name="source">Source Code</a>
 142 </div>
 143 <!-- *********************************************************************** -->
 144
 145 <div class="question">
 146 <p>In what language is LLVM written?</p>
 147 </div>
 148
 149 <div class="answer">
 150 <p>All of the LLVM tools and libraries are written in C++ with extensive use of
 151 the STL.</p>
 152 </div>
 153
 154 <div class="question">
 155 <p>How portable is the LLVM source code?</p>
 156 </div>
 157
 158 <div class="answer">
 159 <p>The LLVM source code should be portable to most modern UNIX-like operating
 160 systems.  Most of the code is written in standard C++ with operating system
 161 services abstracted to a support library.  The tools required to build and test
 162 LLVM have been ported to a plethora of platforms.</p>
 163
 164 <p>Some porting problems may exist in the following areas:</p>
 165
 166 <ul>
 167
 168   <li>The GCC front end code is not as portable as the LLVM suite, so it may not
 169   compile as well on unsupported platforms.</li>
 170
 171   <li>The Python test classes are more UNIX-centric than they should be, so
 172   porting to non-UNIX like platforms (i.e. Windows, MacOS 9) will require some
 173   effort.</li>
 174
 175   <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
 176   Shell and sed.  Porting to systems without these tools (MacOS 9, Plan 9) will
 177   require more effort.</li>
 178
 179 </ul>
 180
 181 </div>
 182
 183 <!-- *********************************************************************** -->
 184 <div class="doc_section">
 185   <a name="build">Build Problems</a>
 186 </div>
 187 <!-- *********************************************************************** -->
 188
 189 <div class="question">
 190 <p>When I run configure, it finds the wrong C compiler.</p>
 191 </div>
 192
 193 <div class="answer">
 194
 195 <p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
 196 <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt> and <tt>CXX</tt>
 197 for the C and C++ compiler, respectively.</p>
 198
 199 <p>If <tt>configure</tt> finds the wrong compiler, either adjust your
 200 <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
 201 explicitly.</p>
 202
 203 </div>
 204
 205 <div class="question">
 206 <p>I compile the code, and I get some error about <tt>/localhome</tt>.</p>
 207 </div>
 208
 209 <div class="answer">
 210
 211 <p>There are several possible causes for this.  The first is that you didn't set
 212 a pathname properly when using <tt>configure</tt>, and it defaulted to a
 213 pathname that we use on our research machines.</p>
 214
 215 <p>Another possibility is that we hardcoded a path in our Makefiles.  If you see
 216 this, please email the LLVM bug mailing list with the name of the offending
 217 Makefile and a description of what is wrong with it.</p>
 218
 219 </div>
 220
 221 <div class="question">
 222 <p>The <tt>configure</tt> script finds the right C compiler, but it uses the
 223 LLVM linker from a previous build.  What do I do?</p>
 224 </div>
 225
 226 <div class="answer">
 227 <p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
 228 if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
 229 it:</p>
 230
 231 <ol>
 232
 233   <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
 234   program appears first in the <tt>PATH</tt>.  This may work, but may not be
 235   convenient when you want them <i>first</i> in your path for other
 236   work.</p></li>
 237
 238   <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
 239   correct. In a Borne compatible shell, the syntax would be:</p>
 240
 241       <p><tt>PATH=[the path without the bad program] ./configure ...</tt></p>
 242
 243       <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
 244       to do its work without having to adjust your <tt>PATH</tt>
 245       permanently.</p></li>
 246
 247 </ol>
 248
 249 </div>
 250
 251 <div class="question">
 252 <p>When creating a dynamic library, I get a strange GLIBC error.</p>
 253 </div>
 254
 255 <div class="answer">
 256 <p>Under some operating systems (i.e. Linux), libtool does not work correctly if
 257 GCC was compiled with the --disable-shared option.  To work around this, install
 258 your own version of GCC that has shared libraries enabled by default.</p>
 259 </div>
 260
 261 <div class="question">
 262 <p>I've updated my source tree from CVS, and now my build is trying to use a
 263 file/directory that doesn't exist.</p>
 264 </div>
 265
 266 <div class="answer">
 267 <p>You need to re-run configure in your object directory.  When new Makefiles
 268 are added to the source tree, they have to be copied over to the object tree in
 269 order to be used by the build.</p>
 270 </div>
 271
 272 <div class="question">
 273 <p>I've modified a Makefile in my source tree, but my build tree keeps using the
 274 old version.  What do I do?</p>
 275 </div>
 276
 277 <div class="answer">
 278
 279 <p>If the Makefile already exists in your object tree, you
 280 can just run the following command in the top level directory of your object
 281 tree:</p>
 282
 283 <p><tt>./config.status &lt;relative path to Makefile&gt;</tt><p>
 284
 285 <p>If the Makefile is new, you will have to modify the configure script to copy
 286 it over.</p>
 287
 288 </div>
 289
 290 <div class="question">
 291 <p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
 292 </div>
 293
 294 <div class="answer">
 295
 296 <p>Sometimes, changes to the LLVM source code alters how the build system works.
 297 Changes in libtool, autoconf, or header file dependencies are especially prone
 298 to this sort of problem.</p>
 299
 300 <p>The best thing to try is to remove the old files and re-build.  In most
 301 cases, this takes care of the problem.  To do this, just type <tt>make
 302 clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
 303
 304 </div>
 305
 306 <div class="question">
 307 <p>I've built LLVM and am testing it, but the tests freeze.</p>
 308 </div>
 309
 310 <div class="answer">
 311
 312 <p>This is most likely occurring because you built a profile or release
 313 (optimized) build of LLVM and have not specified the same information on the
 314 <tt>gmake</tt> command line.</p>
 315
 316 <p>For example, if you built LLVM with the command:</p>
 317
 318 <p><tt>gmake ENABLE_PROFILING=1</tt>
 319
 320 <p>...then you must run the tests with the following commands:</p>
 321
 322 <p><tt>cd llvm/test<br>gmake  ENABLE_PROFILING=1</tt></p>
 323
 324 </div>
 325
 326 <div class="question">
 327 <p>Why do test results differ when I perform different types of builds?</p>
 328 </div>
 329
 330 <div class="answer">
 331
 332 <p>The LLVM test suite is dependent upon several features of the LLVM tools and
 333 libraries.</p>
 334
 335 <p>First, the debugging assertions in code are not enabled in optimized or
 336 profiling builds.  Hence, tests that used to fail may pass.</p>
 337
 338 <p>Second, some tests may rely upon debugging options or behavior that is only
 339 available in the debug build.  These tests will fail in an optimized or profile
 340 build.</p>
 341
 342 </div>
 343
 344 <div class="question">
 345 <p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
 346 </div>
 347
 348 <div class="answer">
 349 <p>This is <a href="http://gcc.gnu.org/PR?13392">a bug in GCC</a>, and
 350    affects projects other than LLVM.  Try upgrading or downgrading your GCC.</p>
 351 </div>
 352
 353 <div class="question">
 354 <p>
 355 When I use the test suite, all of the C Backend tests fail.  What is
 356 wrong?
 357 </p>
 358 </div>
 359
 360 <div class="answer">
 361 <p>
 362 If you build LLVM and the C Backend tests fail in <tt>llvm/test/Programs</tt>,
 363 then chances are good that the directory pointed to by the LLVM_LIB_SEARCH_PATH
 364 environment variable does not contain the libcrtend.a library.
 365 </p>
 366
 367 <p>
 368 To fix it, verify that LLVM_LIB_SEARCH_PATH points to the correct directory
 369 and that libcrtend.a is inside.  For pre-built LLVM GCC front ends, this
 370 should be the absolute path to
 371 <tt>cfrontend/&lt;<i>platform</i>&gt;/llvm-gcc/bytecode-libs</tt>.  If you've
 372 built your own LLVM GCC front end, then ensure that you've built and installed
 373 the libraries in <tt>llvm/runtime</tt> and have LLVM_LIB_SEARCH_PATH pointing
 374 to the <tt>LLVMGCCDIR/bytecode-libs</tt> subdirectory.
 375 </p>
 376 </div>
 377
 378 <div class="question">
 379 <p>After CVS update, rebuilding gives the error "No rule to make target".</p>
 380 </div>
 381
 382 <div class="answer">
 383 <p>If the error is of the form:</p>
 384
 385 <div class="doc_code">
 386 <tt>
 387 gmake[2]: *** No rule to make target `/path/to/somefile', needed by
 388 `/path/to/another/file.d'.<br>
 389 Stop.
 390 </tt>
 391 </div>
 392
 393 <p>This may occur anytime files are moved within the CVS repository or removed
 394 entirely.  In this case, the best solution is to erase all <tt>.d</tt> files,
 395 which list dependencies for source files, and rebuild:</p>
 396
 397 <div class="doc_code">
 398 <pre>
 399 % cd $LLVM_OBJ_DIR
 400 % rm -f `find . -name \*\.d`
 401 % gmake
 402 </pre>
 403 </div>
 404
 405 <p>In other cases, it may be necessary to run <tt>make clean</tt> before
 406 rebuilding.</p>
 407 </div>
 408
 409 <!-- *********************************************************************** -->
 410 <div class="doc_section">
 411   <a name="cfe">Using the GCC Front End</a>
 412 </div>
 413
 414 <div class="question">
 415 <p>
 416 When I compile software that uses a configure script, the configure script
 417 thinks my system has all of the header files and libraries it is testing for.
 418 How do I get configure to work correctly?
 419 </p>
 420 </div>
 421
 422 <div class="answer">
 423 <p>
 424 The configure script is getting things wrong because the LLVM linker allows
 425 symbols to be undefined at link time (so that they can be resolved during JIT
 426 or translation to the C back end).  That is why configure thinks your system
 427 "has everything."
 428 </p>
 429 <p>
 430 To work around this, perform the following steps:
 431 </p>
 432
 433 <ol>
 434   <li>
 435   Make sure the CC and CXX environment variables contains the full path to the
 436   LLVM GCC front end.
 437   </li>
 438
 439   <li>
 440   Make sure that the regular C compiler is first in your PATH.
 441   </li>
 442
 443   <li>
 444   Add the string "-Wl,-native" to your CFLAGS environment variable.
 445   </li>
 446 </ol>
 447
 448 <p>
 449 This will allow the gccld linker to create a native code executable instead of
 450 a shell script that runs the JIT.  Creating native code requires standard
 451 linkage, which in turn will allow the configure script to find out if code is
 452 not linking on your system because the feature isn't available on your system.
 453 </p>
 454 </div>
 455
 456 <div class="question">
 457 <p>
 458 When I compile code using the LLVM GCC front end, it complains that it cannot
 459 find libcrtend.a.
 460 </p>
 461 </div>
 462
 463 <div class="answer">
 464 <p>
 465 In order to find libcrtend.a, you must have the directory in which it lives in
 466 your LLVM_LIB_SEARCH_PATH environment variable.  For the binary distribution of
 467 the LLVM GCC front end, this will be the full path of the bytecode-libs
 468 directory inside of the LLVM GCC distribution.
 469 </p>
 470 </div>
 471
 472
 473 <!-- *********************************************************************** -->
 474 <div class="doc_section">
 475   <a name="cfe_code">Questions about code generated by the GCC front-end</a>
 476 </div>
 477
 478 <div class="question"><p>
 479 What is this <tt>__main()</tt> call that gets inserted into <tt>main()</tt>?
 480 </p></div>
 481
 482 <div class="answer">
 483 <p>
 484 The <tt>__main</tt> call is inserted by the C/C++ compiler in order to guarantee
 485 that static constructors and destructors are called when the program starts up
 486 and shuts down.  In C, you can create static constructors and destructors by
 487 using GCC extensions, and in C++ you can do so by creating a global variable
 488 whose class has a ctor or dtor.
 489 </p>
 490
 491 <p>
 492 The actual implementation of <tt>__main</tt> lives in the
 493 <tt>llvm/runtime/GCCLibraries/crtend/</tt> directory in the source-base, and is
 494 linked in automatically when you link the program.
 495 </p>
 496 </div>
 497
 498 <!--=========================================================================-->
 499
 500 <div class="question"><p>
 501 Where did all of my code go??
 502 </p></div>
 503
 504 <div class="answer">
 505 <p>
 506 If you are using the LLVM demo page, you may often wonder what happened to all
 507 of the code that you typed in.  Remember that the demo script is running the
 508 code through the LLVM optimizers, so if your code doesn't actually do anything
 509 useful, it might all be deleted.
 510 </p>
 511
 512 <p>
 513 To prevent this, make sure that the code is actually needed.  For example, if
 514 you are computing some expression, return the value from the function instead of
 515 leaving it in a local variable.  If you really want to constrain the optimizer,
 516 you can read from and assign to <tt>volatile</tt> global variables.
 517 </p>
 518 </div>
 519
 520 <!--=========================================================================-->
 521
 522 <div class="question"><p>
 523 What is this <tt>llvm.global_ctors</tt> and <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I #include &lt;iostream&gt;?
 524 </p></div>
 525
 526 <div class="answer">
 527 <p>
 528 If you #include the &lt;iostream&gt; header into a C++ translation unit, the
 529 file will probably use the <tt>std::cin</tt>/<tt>std::cout</tt>/... global
 530 objects.  However, C++ does not guarantee an order of initialization between
 531 static objects in different translation units, so if a static ctor/dtor in your
 532 .cpp file used <tt>std::cout</tt>, for example, the object would not necessarily
 533 be automatically initialized before your use.
 534 </p>
 535
 536 <p>
 537 To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
 538 STL that we use declares a static object that gets created in every translation
 539 unit that includes &lt;iostream&gt;.  This object has a static constructor and
 540 destructor that initializes and destroys the global iostream objects before they
 541 could possibly be used in the file.  The code that you see in the .ll file
 542 corresponds to the constructor and destructor registration code.
 543 </p>
 544
 545 <p>
 546 If you would like to make it easier to <b>understand</b> the LLVM code generated
 547 by the compiler in the demo page, consider using printf instead of iostreams to
 548 print values.
 549 </p>
 550 </div>
 551
 552 <!-- *********************************************************************** -->
 553
 554 <hr>
 555 <address>
 556   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 557   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 558   <a href="http://validator.w3.org/check/referer"><img
 559   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
 560
 561   <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
 562   Last modified: $Date$
 563 </address>
 564
 565 </body>
 566 </html>