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>
   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   </ol></li>
  53
  54   <li><a href="#cfe">Using the GCC Front End</a>
  55   <ol>
  56     <li>
  57     When I compile software that uses a configure script, the configure script
  58     thinks my system has all of the header files and libraries it is testing
  59     for.  How do I get configure to work correctly?
  60     </li>
  61
  62     <li>
  63     When I compile code using the LLVM GCC front end, it complains that it
  64     cannot find crtend.o.
  65     </li>
  66   </ol>
  67   </li>
  68
  69   <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
  70   <ol>
  71      <li>What is this <tt>__main()</tt> call that gets inserted into
  72          <tt>main()</tt>?</li>
  73      <li>Where did all of my code go??</li>
  74   </ol>
  75   </li>
  76 </ol>
  77
  78 <!-- *********************************************************************** -->
  79 <div class="doc_section">
  80   <a name="license">License</a>
  81 </div>
  82 <!-- *********************************************************************** -->
  83
  84 <div class="question">
  85 <p>Why are the LLVM source code and the front-end distributed under different
  86 licenses?</p>
  87 </div>
  88
  89 <div class="answer">
  90 <p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
  91 Our aim is to distribute LLVM source code under a <em>much less restrictive</em>
  92 license, in particular one that does not compel users who distribute tools based
  93 on modifying the source to redistribute the modified source code as well.</p>
  94 </div>
  95
  96 <div class="question">
  97 <p>Does the University of Illinois Open Source License really qualify as an
  98 "open source" license?</p>
  99 </div>
 100
 101 <div class="answer">
 102 <p>Yes, the license is <a
 103 href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open
 104 Source Initiative (OSI).</p>
 105 </div>
 106
 107 <div class="question">
 108 <p>Can I modify LLVM source code and redistribute the modified source?</p>
 109 </div>
 110
 111 <div class="answer">
 112 <p>Yes.  The modified source distribution must retain the copyright notice and
 113 follow the three bulletted conditions listed in the <a
 114 href="http://llvm.cs.uiuc.edu/releases/1.0/LICENSE.TXT">LLVM license</a>.</p>
 115 </div>
 116
 117 <div class="question">
 118 <p>Can I modify LLVM source code and redistribute binaries or other tools based
 119 on it, without redistributing the source?</p>
 120 </div>
 121
 122 <div class="answer">
 123 <p>Yes, this is why we distribute LLVM under a less restrictive license than
 124 GPL, as explained in the first question above.</p>
 125 </div>
 126
 127 <!-- *********************************************************************** -->
 128 <div class="doc_section">
 129   <a name="source">Source Code</a>
 130 </div>
 131 <!-- *********************************************************************** -->
 132
 133 <div class="question">
 134 <p>In what language is LLVM written?</p>
 135 </div>
 136
 137 <div class="answer">
 138 <p>All of the LLVM tools and libraries are written in C++ with extensive use of
 139 the STL.</p>
 140 </div>
 141
 142 <div class="question">
 143 <p>How portable is the LLVM source code?</p>
 144 </div>
 145
 146 <div class="answer">
 147 <p>The LLVM source code should be portable to most modern UNIX-like operating
 148 systems.  Most of the code is written in standard C++ with operating system
 149 services abstracted to a support library.  The tools required to build and test
 150 LLVM have been ported to a plethora of platforms.</p>
 151
 152 <p>Some porting problems may exist in the following areas:</p>
 153
 154 <ul>
 155
 156   <li>The GCC front end code is not as portable as the LLVM suite, so it may not
 157   compile as well on unsupported platforms.</li>
 158
 159   <li>The Python test classes are more UNIX-centric than they should be, so
 160   porting to non-UNIX like platforms (i.e. Windows, MacOS 9) will require some
 161   effort.</li>
 162
 163   <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
 164   Shell and sed.  Porting to systems without these tools (MacOS 9, Plan 9) will
 165   require more effort.</li>
 166
 167 </ul>
 168
 169 </div>
 170
 171 <!-- *********************************************************************** -->
 172 <div class="doc_section">
 173   <a name="build">Build Problems</a>
 174 </div>
 175 <!-- *********************************************************************** -->
 176
 177 <div class="question">
 178 <p>When I run configure, it finds the wrong C compiler.</p>
 179 </div>
 180
 181 <div class="answer">
 182
 183 <p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
 184 <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt> and <tt>CXX</tt>
 185 for the C and C++ compiler, respectively.</p>
 186
 187 <p>If <tt>configure</tt> finds the wrong compiler, either adjust your
 188 <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
 189 explicitly.</p>
 190
 191 </div>
 192
 193 <div class="question">
 194 <p>I compile the code, and I get some error about <tt>/localhome</tt>.</p>
 195 </div>
 196
 197 <div class="answer">
 198
 199 <p>There are several possible causes for this.  The first is that you didn't set
 200 a pathname properly when using <tt>configure</tt>, and it defaulted to a
 201 pathname that we use on our research machines.</p>
 202
 203 <p>Another possibility is that we hardcoded a path in our Makefiles.  If you see
 204 this, please email the LLVM bug mailing list with the name of the offending
 205 Makefile and a description of what is wrong with it.</p>
 206
 207 </div>
 208
 209 <div class="question">
 210 <p>The <tt>configure</tt> script finds the right C compiler, but it uses the
 211 LLVM linker from a previous build.  What do I do?</p>
 212 </div>
 213
 214 <div class="answer">
 215 <p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
 216 if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
 217 it:</p>
 218
 219 <ol>
 220
 221   <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
 222   program appears first in the <tt>PATH</tt>.  This may work, but may not be
 223   convenient when you want them <i>first</i> in your path for other
 224   work.</p></li>
 225
 226   <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
 227   correct. In a Borne compatible shell, the syntax would be:</p>
 228
 229       <p><tt>PATH=<the path without the bad program> ./configure ...</tt></p>
 230
 231       <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
 232       to do its work without having to adjust your <tt>PATH</tt>
 233       permanently.</p></li>
 234
 235 </ol>
 236
 237 </div>
 238
 239 <div class="question">
 240 <p>When creating a dynamic library, I get a strange GLIBC error.</p>
 241 </div>
 242
 243 <div class="answer">
 244 <p>Under some operating systems (i.e. Linux), libtool does not work correctly if
 245 GCC was compiled with the --disable-shared option.  To work around this, install
 246 your own version of GCC that has shared libraries enabled by default.</p>
 247 </div>
 248
 249 <div class="question">
 250 <p>I've updated my source tree from CVS, and now my build is trying to use a
 251 file/directory that doesn't exist.</p>
 252 </div>
 253
 254 <div class="answer">
 255 <p>You need to re-run configure in your object directory.  When new Makefiles
 256 are added to the source tree, they have to be copied over to the object tree in
 257 order to be used by the build.</p>
 258 </div>
 259
 260 <div class="question">
 261 <p>I've modified a Makefile in my source tree, but my build tree keeps using the
 262 old version.  What do I do?</p>
 263 </div>
 264
 265 <div class="answer">
 266
 267 <p>If the Makefile already exists in your object tree, you
 268 can just run the following command in the top level directory of your object
 269 tree:</p>
 270
 271 <p><tt>./config.status &lt;relative path to Makefile&gt;</tt><p>
 272
 273 <p>If the Makefile is new, you will have to modify the configure script to copy
 274 it over.</p>
 275
 276 </div>
 277
 278 <div class="question">
 279 <p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
 280 </div>
 281
 282 <div class="answer">
 283
 284 <p>Sometimes, changes to the LLVM source code alters how the build system works.
 285 Changes in libtool, autoconf, or header file dependencies are especially prone
 286 to this sort of problem.</p>
 287
 288 <p>The best thing to try is to remove the old files and re-build.  In most
 289 cases, this takes care of the problem.  To do this, just type <tt>make
 290 clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
 291
 292 </div>
 293
 294 <div class="question">
 295 <p>I've built LLVM and am testing it, but the tests freeze.</p>
 296 </div>
 297
 298 <div class="answer">
 299
 300 <p>This is most likely occurring because you built a profile or release
 301 (optimized) build of LLVM and have not specified the same information on the
 302 <tt>gmake</tt> command line.</p>
 303
 304 <p>For example, if you built LLVM with the command:</p>
 305
 306 <p><tt>gmake ENABLE_PROFILING=1</tt>
 307
 308 <p>...then you must run the tests with the following commands:</p>
 309
 310 <p><tt>cd llvm/test<br>gmake  ENABLE_PROFILING=1</tt></p>
 311
 312 </div>
 313
 314 <div class="question">
 315 <p>Why do test results differ when I perform different types of builds?</p>
 316 </div>
 317
 318 <div class="answer">
 319
 320 <p>The LLVM test suite is dependent upon several features of the LLVM tools and
 321 libraries.</p>
 322
 323 <p>First, the debugging assertions in code are not enabled in optimized or
 324 profiling builds.  Hence, tests that used to fail may pass.</p>
 325
 326 <p>Second, some tests may rely upon debugging options or behavior that is only
 327 available in the debug build.  These tests will fail in an optimized or profile
 328 build.</p>
 329
 330 </div>
 331
 332 <div class="question">
 333 <p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
 334 </div>
 335
 336 <div class="answer">
 337 <p>This is <a href="http://gcc.gnu.org/PR?13392">a bug in GCC</a>, and
 338    affects projects other than LLVM.  Try upgrading or downgrading your GCC.</p>
 339 </div>
 340
 341 <!-- *********************************************************************** -->
 342 <div class="doc_section">
 343   <a name="cfe">Using the GCC Front End</a>
 344 </div>
 345
 346 <div class="question">
 347 <p>
 348 When I compile software that uses a configure script, the configure script
 349 thinks my system has all of the header files and libraries it is testing for.
 350 How do I get configure to work correctly?
 351 </p>
 352 </div>
 353
 354 <div class="answer">
 355 <p>
 356 The configure script is getting things wrong because the LLVM linker allows
 357 symbols to be undefined at link time (so that they can be resolved during JIT
 358 or translation to the C back end).  That is why configure thinks your system
 359 "has everything."
 360 </p>
 361 <p>
 362 To work around this, perform the following steps:
 363 </p>
 364
 365 <ol>
 366   <li>
 367   Make sure the CC and CXX environment variables contains the full path to the
 368   LLVM GCC front end.
 369   </li>
 370
 371   <li>
 372   Make sure that the regular C compiler is first in your PATH.
 373   </li>
 374
 375   <li>
 376   Add the string "-Wl,-native" to your CFLAGS environment variable.
 377   </li>
 378 </ol>
 379
 380 <p>
 381 This will allow the gccld linker to create a native code executable instead of
 382 a shell script that runs the JIT.  Creating native code requires standard
 383 linkage, which in turn will allow the configure script to find out if code is
 384 not linking on your system because the feature isn't available on your system.
 385 </p>
 386 </div>
 387
 388 <div class="question">
 389 <p>
 390 When I compile code using the LLVM GCC front end, it complains that it cannot
 391 find crtend.o.
 392 </p>
 393 </div>
 394
 395 <div class="answer">
 396 <p>
 397 In order to find crtend.o, you must have the directory in which it lives in
 398 your LLVM_LIB_SEARCH_PATH environment variable.  For the binary distribution of
 399 the LLVM GCC front end, this will be the full path of the bytecode-libs
 400 directory inside of the LLVM GCC distribution.
 401 </p>
 402 </div>
 403
 404
 405 <!-- *********************************************************************** -->
 406 <div class="doc_section">
 407   <a name="cfe_code">Questions about code generated by the GCC front-end</a>
 408 </div>
 409
 410 <div class="question"><p>
 411 What is this <tt>__main()</tt> call that gets inserted into <tt>main()</tt>?
 412 </p></div>
 413
 414 <div class="answer">
 415 <p>
 416 The <tt>__main</tt> call is inserted by the C/C++ compiler in order to guarantee
 417 that static constructors and destructors are called when the program starts up
 418 and shuts down.  In C, you can create static constructors and destructors by
 419 using GCC extensions, and in C++ you can do so by creating a global variable
 420 whose class has a ctor or dtor.
 421 </p>
 422
 423 <p>
 424 The actual implementation of <tt>__main</tt> lives in the
 425 <tt>llvm/runtime/GCCLibraries/crtend/</tt> directory in the source-base, and is
 426 linked in automatically when you link the program.
 427 </p>
 428 </div>
 429
 430 <!--=========================================================================-->
 431
 432 <div class="question"><p>
 433 Where did all of my code go??
 434 </p></div>
 435
 436 <div class="answer">
 437 <p>
 438 If you are using the LLVM demo page, you may often wonder what happened to all
 439 of the code that you typed in.  Remember that the demo script is running the
 440 code through the LLVM optimizers, so if your code doesn't actually do anything
 441 useful, it might all be deleted.
 442 </p>
 443
 444 <p>
 445 To prevent this, make sure that the code is actually needed.  For example, if
 446 you are computing some expression, return the value from the function instead of
 447 leaving it in a local variable.  If you really want to constrain the optimizer,
 448 you can read from and assign to <tt>volatile</tt> global variables.
 449 </p>
 450 </div>
 451
 452 <!-- *********************************************************************** -->
 453 <!-- *********************************************************************** -->
 454
 455 <hr>
 456 <div class="doc_footer">
 457   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
 458   <br>
 459   Last modified: $Date$
 460 </div>
 461
 462 </body>
 463 </html>