Home | History | Annotate | Download | only in docs
      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   <title>Advice on Packaging LLVM</title>
      7   <link rel="stylesheet" href="llvm.css" type="text/css">
      8 </head>
      9 <body>
     10 
     11 <h1>Advice on Packaging LLVM</h1>
     12 <ol>
     13   <li><a href="#overview">Overview</a></li>
     14   <li><a href="#compilation">Compile Flags</a></li>
     15   <li><a href="#cxx-features">C++ Features</a></li>
     16   <li><a href="#shared-library">Shared Library</a></li>
     17   <li><a href="#deps">Dependencies</a></li>
     18 </ol>
     19 
     20 <!--=========================================================================-->
     21 <h2><a name="overview">Overview</a></h2>
     22 <!--=========================================================================-->
     23 <div>
     24 
     25 <p>LLVM sets certain default configure options to make sure our developers don't
     26 break things for constrained platforms.  These settings are not optimal for most
     27 desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
     28 etc.) will tweak them.  This document lists settings we suggest you tweak.
     29 </p>
     30 
     31 <p>LLVM's API changes with each release, so users are likely to want, for
     32 example, both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps
     33 developed against each.
     34 </p>
     35 </div>
     36 
     37 <!--=========================================================================-->
     38 <h2><a name="compilation">Compile Flags</a></h2>
     39 <!--=========================================================================-->
     40 <div>
     41 
     42 <p>LLVM runs much more quickly when it's optimized and assertions are removed.
     43 However, such a build is currently incompatible with users who build without
     44 defining NDEBUG, and the lack of assertions makes it hard to debug problems in
     45 user code.  We recommend allowing users to install both optimized and debug
     46 versions of LLVM in parallel.  The following configure flags are relevant:
     47 </p>
     48 
     49 <dl>
     50   <dt><tt>--disable-assertions</tt></dt><dd>Builds LLVM with <tt>NDEBUG</tt>
     51   defined.  Changes the LLVM ABI.  Also available by setting
     52   <tt>DISABLE_ASSERTIONS=0|1</tt> in <tt>make</tt>'s environment.  This defaults
     53   to enabled regardless of the optimization setting, but it slows things
     54   down.</dd>
     55 
     56   <dt><tt>--enable-debug-symbols</tt></dt><dd>Builds LLVM with <tt>-g</tt>.
     57   Also available by setting <tt>DEBUG_SYMBOLS=0|1</tt> in <tt>make</tt>'s
     58   environment.  This defaults to disabled when optimizing, so you should turn it
     59   back on to let users debug their programs.</dd>
     60 
     61   <dt><tt>--enable-optimized</tt></dt><dd>(For svn checkouts) Builds LLVM with
     62   <tt>-O2</tt> and, by default, turns off debug symbols.  Also available by
     63   setting <tt>ENABLE_OPTIMIZED=0|1</tt> in <tt>make</tt>'s environment.  This
     64   defaults to enabled when not in a checkout.</dd>
     65 </dl>
     66 </div>
     67 
     68 <!--=========================================================================-->
     69 <h2><a name="cxx-features">C++ Features</a></h2>
     70 <!--=========================================================================-->
     71 <div>
     72 
     73 <dl>
     74   <dt>RTTI</dt><dd>LLVM disables RTTI by default.  Add <tt>REQUIRES_RTTI=1</tt>
     75   to your environment while running <tt>make</tt> to re-enable it.  This will
     76   allow users to build with RTTI enabled and still inherit from LLVM
     77   classes.</dd>
     78 </dl>
     79 </div>
     80 
     81 <!--=========================================================================-->
     82 <h2><a name="shared-library">Shared Library</a></h2>
     83 <!--=========================================================================-->
     84 <div>
     85 
     86 <p>Configure with <tt>--enable-shared</tt> to build
     87 <tt>libLLVM-<var>major</var>.<var>minor</var>.(so|dylib)</tt> and link the tools
     88 against it.  This saves lots of binary size at the cost of some startup time.
     89 </p>
     90 </div>
     91 
     92 <!--=========================================================================-->
     93 <h2><a name="deps">Dependencies</a></h2>
     94 <!--=========================================================================-->
     95 <div>
     96 
     97 <dl>
     98 <dt><tt>--enable-libffi</tt></dt><dd>Depend on <a
     99 href="http://sources.redhat.com/libffi/">libffi</a> to allow the LLVM
    100 interpreter to call external functions.</dd>
    101 <dt><tt>--with-oprofile</tt></dt><dd>Depend on <a
    102 href="http://oprofile.sourceforge.net/doc/devel/index.html">libopagent</a>
    103 (>=version 0.9.4) to let the LLVM JIT tell oprofile about function addresses and
    104 line numbers.</dd>
    105 </dl>
    106 </div>
    107 
    108 <!-- *********************************************************************** -->
    109 <hr>
    110 <address>
    111   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
    112   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
    113   <a href="http://validator.w3.org/check/referer"><img
    114   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
    115   <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
    116   Last modified: $Date$
    117 </address>
    118 </body>
    119 </html>
    120