| Bill Wendling | 1d4e628 | 2012-06-21 06:09:37 +0000 | [diff] [blame] | 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. |