1========================
2Advice on Packaging LLVM
3========================
4
5.. contents::
6   :local:
7
8Overview
9========
10
11LLVM sets certain default configure options to make sure our developers don't
12break things for constrained platforms.  These settings are not optimal for most
13desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
14etc.) will tweak them.  This document lists settings we suggest you tweak.
15
16LLVM's API changes with each release, so users are likely to want, for example,
17both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps developed
18against each.
19
20Compile Flags
21=============
22
23LLVM runs much more quickly when it's optimized and assertions are removed.
24However, such a build is currently incompatible with users who build without
25defining ``NDEBUG``, and the lack of assertions makes it hard to debug problems
26in user code.  We recommend allowing users to install both optimized and debug
27versions 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
46C++ Features
47============
48
49RTTI
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
54Shared Library
55==============
56
57Configure with ``--enable-shared`` to build
58``libLLVM-<major>.<minor>.(so|dylib)`` and link the tools against it.  This
59saves lots of binary size at the cost of some startup time.
60
61Dependencies
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