Home | History | Annotate | Download | only in docs 
      1 ========================
      2 Advice on Packaging LLVM
      3 ========================
      4 
      5 .. contents::
      6    :local:
      7 
      8 Overview
      9 ========
     10 
     11 LLVM sets certain default configure options to make sure our developers don't
     12 break things for constrained platforms.  These settings are not optimal for most
     13 desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
     14 etc.) will tweak them.  This document lists settings we suggest you tweak.
     15 
     16 LLVM's API changes with each release, so users are likely to want, for example,
     17 both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps developed
     18 against each.
     19 
     20 Compile Flags
     21 =============
     22 
     23 LLVM runs much more quickly when it's optimized and assertions are removed.
     24 However, such a build is currently incompatible with users who build without
     25 defining ``NDEBUG``, and the lack of assertions makes it hard to debug problems
     26 in user code.  We recommend allowing users to install both optimized and debug
     27 versions of LLVM in parallel.  The following configure flags are relevant:
     28 
     29 ``--disable-assertions``
     30     Builds LLVM with ``NDEBUG`` defined.  Changes the LLVM ABI.  Also available
     31     by setting ``DISABLE_ASSERTIONS=0|1`` in ``make``'s environment.  This
     32     defaults to enabled regardless of the optimization setting, but it slows
     33     things down.
     34 
     35 ``--enable-debug-symbols``
     36     Builds LLVM with ``-g``.  Also available by setting ``DEBUG_SYMBOLS=0|1`` in
     37     ``make``'s environment.  This defaults to disabled when optimizing, so you
     38     should turn it back on to let users debug their programs.
     39 
     40 ``--enable-optimized``
     41     (For svn checkouts) Builds LLVM with ``-O2`` and, by default, turns off
     42     debug symbols.  Also available by setting ``ENABLE_OPTIMIZED=0|1`` in
     43     ``make``'s environment.  This defaults to enabled when not in a
     44     checkout.
     45 
     46 C++ Features
     47 ============
     48 
     49 RTTI
     50     LLVM disables RTTI by default.  Add ``REQUIRES_RTTI=1`` to your environment
     51     while running ``make`` to re-enable it.  This will allow users to build with
     52     RTTI enabled and still inherit from LLVM classes.
     53 
     54 Shared Library
     55 ==============
     56 
     57 Configure with ``--enable-shared`` to build
     58 ``libLLVM-<major>.<minor>.(so|dylib)`` and link the tools against it.  This
     59 saves lots of binary size at the cost of some startup time.
     60 
     61 Dependencies
     62 ============
     63 
     64 ``--enable-libffi``
     65     Depend on `libffi <http://sources.redhat.com/libffi/>`_ to allow the LLVM
     66     interpreter to call external functions.
     67 
     68 ``--with-oprofile``
     69 
     70     Depend on `libopagent
     71     <http://oprofile.sourceforge.net/doc/devel/index.html>`_ (>=version 0.9.4)
     72     to let the LLVM JIT tell oprofile about function addresses and line
     73     numbers.
     74