docs/CFEBuildInstrs.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   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   6   <link rel="stylesheet" href="llvm.css" type="text/css" media="screen">
   7   <title>Bootstrapping the LLVM C/C++ Front-End</title>
   8 </head>
   9 <body>
  10
  11 <div class="doc_title">
  12   Bootstrapping the LLVM C/C++ Front-End
  13 </div>
  14
  15 <ol>
  16   <li><a href="#cautionarynote">A Cautionary Note</a>
  17     <ul>
  18       <li><a href="#cygwin">Building under Cygwin</a></li>
  19       <li><a href="#aix">Building under AIX</a></li>
  20     </ul>
  21   </li>
  22   <li><a href="#instructions">Instructions</a></li>
  23   <li><a href="#license">License Information</a></li>
  24 </ol>
  25
  26 <div class="doc_author">
  27   <p>Written by Brian R. Gaeke and
  28      <a href="http://nondot.org/sabre">Chris Lattner</a></p>
  29 </div>
  30
  31 <!-- *********************************************************************** -->
  32 <div class="doc_section">
  33   <a name="cautionarynote">A Cautionary Note</a>
  34 </div>
  35 <!-- *********************************************************************** -->
  36
  37 <div class="doc_text">
  38 <p>This document is intended to explain the process of building the
  39 LLVM C/C++ front-end, based on GCC 3.4, from its source code. You
  40 would have to do this, for example, if you are porting LLVM to a new
  41 architecture or operating system.</p>
  42
  43 <p><b>NOTE:</b> This is currently a somewhat fragile, error-prone
  44 process, and you should <b>only</b> try to do it if:</p>
  45
  46 <ol>
  47   <li>you really, really, really can't use the binaries we distribute</li>
  48   <li>you are an elite GCC hacker.</li>
  49   <li>you want to use the latest bits from CVS.</li>
  50 </ol>
  51
  52 <p>We welcome patches to help make this process simpler.</p>
  53 </div>
  54
  55 <!--=========================================================================-->
  56 <div class="doc_subsection">
  57   <a name="cygwin">Building under Cygwin</a>
  58 </div>
  59 <!--=========================================================================-->
  60
  61 <div class="doc_text">
  62 <p>If you are building LLVM and the GCC front-end under Cygwin, please note that
  63 the LLVM and GCC makefiles do not correctly handle spaces in paths.  To deal
  64 with this issue, make sure that your LLVM and GCC source and build trees are
  65 located in a top-level directory (like <tt>/cygdrive/c/llvm</tt> and
  66 <tt>/cygdrive/c/llvm-cfrontend</tt>), not in a directory that contains a space
  67 (which includes your "home directory", because it lives under the "Documents
  68 and Settings" directory).  We welcome patches to fix this issue.
  69 </p>
  70 <p>It has been found that the GCC 3.3.3 compiler provided with recent Cygwin
  71 versions is incapable of compiling the LLVM CFE correctly. If your Cygwin
  72 installation includes GCC 3.3.3, we <i>strongly</i> recommend that you download
  73 GCC 3.4.3, build it separately, and use it for compiling LLVM CFE. This has been
  74 shown to work correctly.</p>
  75 <p>Some versions of Cygwin utilize an experimental version of GNU binutils that
  76 will cause the GNU <tt>ld</tt> linker to fail an assertion when linking
  77 components of the libstdc++. It is recommended that you replace the entire
  78 binutils package with version 2.15 such that "<tt>ld --version</tt>" responds
  79 with</p>
  80 <pre>GNU ld version 2.15</pre>
  81 not with:<br/>
  82 <pre>GNU ld version 2.15.91 20040725</pre>
  83 </div>
  84
  85 <!--=========================================================================-->
  86 <div class="doc_subsection"><a name="aix">Building under AIX</a></div>
  87 <div class="doc_text">
  88 <p>If you are building LLVM and the GCC front-end under AIX, do NOT use GNU
  89 Binutils.  They are not stable under AIX and may produce incorrect and/or
  90 invalid code.  Instead, use the system assembler and linker.
  91 </p>
  92 </div>
  93
  94 <!-- *********************************************************************** -->
  95 <div class="doc_section">
  96   <a name="instructions">Instructions</a>
  97 </div>
  98 <!-- *********************************************************************** -->
  99
 100 <div class="doc_text">
 101 <p>
 102 <ol>
 103 <li><p>Configure and build the LLVM libraries and tools. There are two ways to
 104 do this: either with <i>objdir</i> == <i>srcdir</i> or
 105 <i>objdir</i> != <i>srcdir</i>. It is recommended
 106 that <i>srcdir</i> not be the same as <i>objdir</i>:</p>
 107 <ul>
 108   <li>With <i>objdir</i> != <i>srcdir</i>:<pre>
 109  % cd <i>objdir</i>
 110  % <i>srcdir</i>/configure --prefix=/some/path/you/can/install/to [options...]
 111  % gmake tools-only
 112   </pre></li>
 113   <li>With <i>objdir</i> == <i>srcdir</i>:<pre>
 114  % cd llvm
 115  % ./configure --prefix=/some/path/you/can/install/to [options...]
 116  % gmake tools-only
 117   </pre></li>
 118 </ul>
 119 <p>This will build all of the LLVM tools and libraries. The <tt>--prefix</tt>
 120 option defaults to /usr/local (per configure standards) but unless you are a
 121 system administrator, you probably won't be able to install LLVM there because
 122 of permissions. Specify a path into which LLVM can be installed (e.g.
 123 <tt>--prefix=/home/user/llvm</tt>).</p>
 124 </li>
 125
 126 <li><p>Add the directory containing the tools to your PATH.</p>
 127 <pre>
 128  % set path = ( `cd llvm/Debug/bin &amp;&amp; pwd` $path )
 129 </pre></li>
 130
 131 <li><p>Unpack the C/C++ front-end source into cfrontend/src, either by
 132        untar'ing an llvm-gcc.tar.gz file or checking out CVS into this
 133        directory.</p></li>
 134
 135 <li><p>Make "build" and "install" directories as siblings of the "src" tree:</p>
 136 <pre>
 137  % pwd
 138  /usr/local/example/cfrontend/src
 139  % cd ..
 140  % mkdir build install
 141  % set CFEINSTALL = `pwd`/install
 142 </pre></li>
 143
 144
 145 <li><p>Configure, build, and install the GCC front-end:</p>
 146
 147 <p>
 148 <b>Linux/x86:</b><br>
 149 <b>MacOS X/PowerPC</b> (requires dlcompat library):<br>
 150 <b>AIX/PowerPC:</b>
 151 </p>
 152
 153 <pre>
 154  % cd build
 155  % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
 156    --disable-shared --enable-languages=c,c++ --program-prefix=llvm-
 157  % gmake all; gmake install
 158 </pre>
 159
 160 <p><b>Cygwin/x86:</b></p>
 161
 162 <pre>
 163  % cd build
 164  % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
 165    --disable-shared --enable-languages=c,c++ --disable-c-mbchar \
 166    --program-prefix=llvm-
 167  % gmake all; gmake install
 168 </pre>
 169
 170 <p><b>Solaris/SPARC:</b></p>
 171
 172 <p>
 173 The GCC front-end can be configured for either SPARC V8 (32 bit) or SPARC V9 (64
 174 bit).  This changes, among other things, the sizes of integer types and the
 175 macros defined for conditional compilation.
 176 </p>
 177
 178 <p>
 179 The SPARC V8 backend is still beta quality software.  Unless you are working on
 180 the SPARC V8 backend, you should specify sparcv9 on the configure command line,
 181 as shown below. Also,
 182 note that Solaris has trouble with various wide (multibyte) character
 183 functions from C as referenced from C++, so we typically configure with
 184 --disable-c-mbchar (cf. <a href="http://llvm.cs.uiuc.edu/PR206">Bug 206</a>).
 185 </p>
 186
 187 <pre>
 188  % cd build
 189  % ../src/configure --prefix=$CFEINSTALL --disable-threads --disable-nls \
 190    --disable-shared --enable-languages=c,c++ --host=sparcv9-sun-solaris2.8 \
 191    --disable-c-mbchar --program-prefix=llvm-
 192  % gmake all; gmake install
 193 </pre>
 194
 195  <p><b>Common Problem:</b> You may get error messages regarding the fact
 196  that LLVM does not support inline assembly. Here are two common
 197  fixes:</p>
 198
 199  <ul>
 200   <li><p><b>Fix 1:</b> If you have system header files that include
 201    inline assembly, you may have to modify them to remove the inline
 202    assembly and install the modified versions in
 203    <code>$CFEINSTALL/lib/gcc/<i>target-triplet</i>/3.4-llvm/include</code>.</li>
 204
 205   <li><b>Fix 2:</b> If you are building the C++ front-end on a CPU we
 206    haven't tried yet, you will probably have to edit the appropriate
 207    version of atomicity.h under
 208    <code>src/libstdc++-v3/config/cpu/<i>name-of-cpu</i>/atomicity.h</code>
 209    and apply a patch so that it does not use inline assembly.</li>
 210  </ul>
 211
 212  <p><b>Porting to a new architecture:</b> If you are porting the front-end
 213  to a new architecture or compiling in a configuration that we have
 214  not tried previously, there are probably several changes you will have to make
 215  to the GCC target to get it to work correctly.  These include:<p>
 216
 217  <ul>
 218   <li>Often targets include special assembler or linker flags which
 219       <tt>gccas</tt>/<tt>gccld</tt> does not understand.  In general, these can
 220       just be removed.</li>
 221   <li>LLVM currently does not support any floating point values other than
 222       32-bit and 64-bit IEEE floating point.  The primary effect of this is
 223       that you may have to map "long double" onto "double".</li>
 224   <li>The profiling hooks in GCC do not apply at all to the LLVM front-end.
 225       These may need to be disabled.</li>
 226   <li>No inline assembly for position independent code.  At the LLVM level,
 227       everything is position independent.</li>
 228   <li>We handle <tt>.init</tt> and <tt>.fini</tt> differently.</li>
 229   <li>You may have to disable multilib support in your target.  Using multilib
 230       support causes the GCC compiler driver to add a lot of "<tt>-L</tt>"
 231       options to the link line, which do not relate to LLVM and confuse
 232       <tt>gccld</tt>.  To disable multilibs, delete any
 233       <tt>MULTILIB_OPTIONS</tt> lines from your target files.</li>
 234   <li>Did we mention that we don't support inline assembly?  You'll probably
 235       have to add some fixinclude hacks to disable it in the system
 236       headers.</li>
 237  </ul>
 238 </li>
 239
 240 <li><p>Put <tt>$CFEINSTALL/bin</tt> into your <tt>PATH</tt> environment
 241 variable.</p>
 242   <ul>
 243     <li>sh: <tt>export PATH=$CFEINSTALL/bin:$PATH</tt></li>
 244     <li>csh: <tt>setenv PATH $CFEINSTALL/bin:$PATH</tt></li>
 245   </ul>
 246 </li>
 247
 248 <li><p>Go back into the LLVM source tree proper.  Rerun configure, using
 249 the same options as the last time. This will cause the configuration to now find
 250 the newly built llvm-gcc and llvm-g++ executables. </p></li>
 251
 252 <li><p>Rebuild your CVS tree.  This shouldn't cause the whole thing to be
 253   rebuilt, but it should build the runtime libraries.  After the tree is
 254   built, install the runtime libraries into your GCC front-end build tree.
 255   These are the commands you need:</p>
 256 <pre>
 257  % gmake
 258  % gmake -C runtime install-bytecode
 259 </pre></li>
 260
 261 <li><p>Optionally, build a symbol table for the newly installed runtime
 262 libraries. Although this step is optional, you are strongly encouraged to
 263 do this as the symbol tables will make a significant difference in your
 264 link times. Use the <tt>llvm-ranlib</tt> tool to do this, as follows:</p>
 265 <pre>
 266  % cd $CFEINSTALL/lib
 267  % llvm-ranlib libiberty.a
 268  % llvm-ranlib libstdc++.a
 269  % llvm-ranlib libsupc++.a
 270  % cd $CFEINSTALL/lib/gcc/<i>target-triplet</i>/3.4-llvm
 271  % llvm-ranlib libgcc.a
 272  % llvm-ranlib libgcov.a
 273 </pre>
 274
 275 <li><p>Test the newly-installed C frontend by one or more of the
 276 following means:</p>
 277  <ul>
 278   <li> running the feature &amp; regression tests via <tt>make check</tt></li>
 279   <li> compiling and running a "hello, LLVM" program in C and C++.</li>
 280   <li> running the tests found in the <tt>llvm-test</tt> CVS module</li>
 281  </ul></li>
 282 </ol>
 283 </div>
 284
 285 <!-- *********************************************************************** -->
 286 <div class="doc_section">
 287   <a name="license">License Information</a>
 288 </div>
 289
 290 <div class="doc_text">
 291 <p>
 292 The LLVM GCC frontend is licensed to you under the GNU General Public License
 293 and the GNU Lesser General Public License.  Please see the files COPYING and
 294 COPYING.LIB for more details.
 295 </p>
 296
 297 <p>
 298 The software also has the following additional copyrights:
 299 </p>
 300
 301 <pre>
 302
 303 Copyright (c) 2003, 2004, 2005 University of Illinois at Urbana-Champaign.
 304 All rights reserved.
 305
 306 Developed by:
 307
 308     LLVM Team
 309
 310     University of Illinois at Urbana-Champaign
 311
 312     http://llvm.cs.uiuc.edu
 313
 314 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 315 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 316 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
 317 CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 318 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 319 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE
 320 SOFTWARE.
 321
 322 Copyright (c) 1994
 323 Hewlett-Packard Company
 324
 325 Permission to use, copy, modify, distribute and sell this software
 326 and its documentation for any purpose is hereby granted without fee,
 327 provided that the above copyright notice appear in all copies and
 328 that both that copyright notice and this permission notice appear
 329 in supporting documentation.  Hewlett-Packard Company makes no
 330 representations about the suitability of this software for any
 331 purpose.  It is provided "as is" without express or implied warranty.
 332
 333 Copyright (c) 1996, 1997, 1998, 1999
 334 Silicon Graphics Computer Systems, Inc.
 335
 336 Permission to use, copy, modify, distribute and sell this software
 337 and its documentation for any purpose is hereby granted without fee,
 338 provided that the above copyright notice appear in all copies and
 339 that both that copyright notice and this permission notice appear
 340 in supporting documentation.  Silicon Graphics makes no
 341 representations about the suitability of this software for any
 342 purpose.  It is provided "as is" without express or implied warranty.
 343 </pre>
 344 </div>
 345
 346 <!-- *********************************************************************** -->
 347
 348 <hr>
 349 <address>
 350   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 351   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
 352   <a href="http://validator.w3.org/check/referer"><img
 353   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
 354
 355   Brian Gaeke<br>
 356   <a href="http://llvm.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
 357   Last modified: $Date$
 358 </address>
 359
 360 </body>
 361 </html>