llvm-mirror/docs/Packaging.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <title>Advice on Packaging LLVM</title>
  <link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>

<h1>Advice on Packaging LLVM</h1>
<ol>
  <li><a href="#overview">Overview</a></li>
  <li><a href="#compilation">Compile Flags</a></li>
  <li><a href="#cxx-features">C++ Features</a></li>
  <li><a href="#shared-library">Shared Library</a></li>
  <li><a href="#deps">Dependencies</a></li>
</ol>

<!--=========================================================================-->
<h2><a name="overview">Overview</a></h2>
<!--=========================================================================-->
<div>

<p>LLVM sets certain default configure options to make sure our developers don't
break things for constrained platforms.  These settings are not optimal for most
desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
etc.) will tweak them.  This document lists settings we suggest you tweak.
</p>

<p>LLVM's API changes with each release, so users are likely to want, for
example, both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps
developed against each.
</p>
</div>

<!--=========================================================================-->
<h2><a name="compilation">Compile Flags</a></h2>
<!--=========================================================================-->
<div>

<p>LLVM runs much more quickly when it's optimized and assertions are removed.
However, such a build is currently incompatible with users who build without
defining NDEBUG, and the lack of assertions makes it hard to debug problems in
user code.  We recommend allowing users to install both optimized and debug
versions of LLVM in parallel.  The following configure flags are relevant:
</p>

<dl>
  <dt><tt>--disable-assertions</tt></dt><dd>Builds LLVM with <tt>NDEBUG</tt>
  defined.  Changes the LLVM ABI.  Also available by setting
  <tt>DISABLE_ASSERTIONS=0|1</tt> in <tt>make</tt>'s environment.  This defaults
  to enabled regardless of the optimization setting, but it slows things
  down.</dd>

  <dt><tt>--enable-debug-symbols</tt></dt><dd>Builds LLVM with <tt>-g</tt>.
  Also available by setting <tt>DEBUG_SYMBOLS=0|1</tt> in <tt>make</tt>'s
  environment.  This defaults to disabled when optimizing, so you should turn it
  back on to let users debug their programs.</dd>

  <dt><tt>--enable-optimized</tt></dt><dd>(For svn checkouts) Builds LLVM with
  <tt>-O2</tt> and, by default, turns off debug symbols.  Also available by
  setting <tt>ENABLE_OPTIMIZED=0|1</tt> in <tt>make</tt>'s environment.  This
  defaults to enabled when not in a checkout.</dd>
</dl>
</div>

<!--=========================================================================-->
<h2><a name="cxx-features">C++ Features</a></h2>
<!--=========================================================================-->
<div>

<dl>
  <dt>RTTI</dt><dd>LLVM disables RTTI by default.  Add <tt>REQUIRES_RTTI=1</tt>
  to your environment while running <tt>make</tt> to re-enable it.  This will
  allow users to build with RTTI enabled and still inherit from LLVM
  classes.</dd>
</dl>
</div>

<!--=========================================================================-->
<h2><a name="shared-library">Shared Library</a></h2>
<!--=========================================================================-->
<div>

<p>Configure with <tt>--enable-shared</tt> to build
<tt>libLLVM-<var>major</var>.<var>minor</var>.(so|dylib)</tt> and link the tools
against it.  This saves lots of binary size at the cost of some startup time.
</p>
</div>

<!--=========================================================================-->
<h2><a name="deps">Dependencies</a></h2>
<!--=========================================================================-->
<div>

<dl>
<dt><tt>--enable-libffi</tt></dt><dd>Depend on <a
href="http://sources.redhat.com/libffi/">libffi</a> to allow the LLVM
interpreter to call external functions.</dd>
<dt><tt>--with-oprofile</tt></dt><dd>Depend on <a
href="http://oprofile.sourceforge.net/doc/devel/index.html">libopagent</a>
(>=version 0.9.4) to let the LLVM JIT tell oprofile about function addresses and
line numbers.</dd>
</dl>
</div>

<!-- *********************************************************************** -->
<hr>
<address>
  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
  <a href="http://validator.w3.org/check/referer"><img
  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
  Last modified: $Date$
</address>
</body>
</html>
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"`
			`"http://www.w3.org/TR/html4/strict.dtd">`
			`<html>`
			`<head>`
			`<title>Advice on Packaging LLVM</title>`
			`<link rel="stylesheet" href="llvm.css" type="text/css">`
			`</head>`
			`<body>`

docs: Use <Hn> as Heading elements instead of <DIV class="doc_foo">. H1 ... doc_title H2 ... doc_section H3 ... doc_subsection H4 ... doc_subsubsection llvm-svn: 129736 2011-04-19 01:59:50 +02:00			`<h1>Advice on Packaging LLVM</h1>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<ol>`
			`<li><a href="#overview">Overview</a></li>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00			`<li><a href="#compilation">Compile Flags</a></li>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<li><a href="#cxx-features">C++ Features</a></li>`
			`<li><a href="#shared-library">Shared Library</a></li>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00			`<li><a href="#deps">Dependencies</a></li>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`</ol>`

			`<!--=========================================================================-->`
docs: Use <Hn> as Heading elements instead of <DIV class="doc_foo">. H1 ... doc_title H2 ... doc_section H3 ... doc_subsection H4 ... doc_subsubsection llvm-svn: 129736 2011-04-19 01:59:50 +02:00			`<h2><a name="overview">Overview</a></h2>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<!--=========================================================================-->`
docs: Introduce cascading style <div> and <p> continued on <h[2-5]>. <h2>Section Example</h2> <div> <!-- h2+div is applied --> <p>Section preamble.</p> <h3>Subsection Example</h3> <p> <!-- h3+p is applied --> Subsection body </p> <!-- End of section body --> </div> FIXME: Care H5 better. llvm-svn: 130040 2011-04-23 02:30:22 +02:00			`<div>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00
			`<p>LLVM sets certain default configure options to make sure our developers don't`
			`break things for constrained platforms. These settings are not optimal for most`
Test that docs are updating. llvm-svn: 97279 2010-02-26 23:25:06 +01:00			`desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`etc.) will tweak them. This document lists settings we suggest you tweak.`
			`</p>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00
			`<p>LLVM's API changes with each release, so users are likely to want, for`
			`example, both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps`
			`developed against each.`
			`</p>`
			`</div>`

			`<!--=========================================================================-->`
docs: Use <Hn> as Heading elements instead of <DIV class="doc_foo">. H1 ... doc_title H2 ... doc_section H3 ... doc_subsection H4 ... doc_subsubsection llvm-svn: 129736 2011-04-19 01:59:50 +02:00			`<h2><a name="compilation">Compile Flags</a></h2>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00			`<!--=========================================================================-->`
docs: Introduce cascading style <div> and <p> continued on <h[2-5]>. <h2>Section Example</h2> <div> <!-- h2+div is applied --> <p>Section preamble.</p> <h3>Subsection Example</h3> <p> <!-- h3+p is applied --> Subsection body </p> <!-- End of section body --> </div> FIXME: Care H5 better. llvm-svn: 130040 2011-04-23 02:30:22 +02:00			`<div>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00
			`<p>LLVM runs much more quickly when it's optimized and assertions are removed.`
			`However, such a build is currently incompatible with users who build without`
			`defining NDEBUG, and the lack of assertions makes it hard to debug problems in`
			`user code. We recommend allowing users to install both optimized and debug`
			`versions of LLVM in parallel. The following configure flags are relevant:`
			`</p>`

			`<dl>`
			`<dt><tt>--disable-assertions</tt></dt><dd>Builds LLVM with <tt>NDEBUG</tt>`
			`defined. Changes the LLVM ABI. Also available by setting`
			`<tt>DISABLE_ASSERTIONS=0\|1</tt> in <tt>make</tt>'s environment. This defaults`
			`to enabled regardless of the optimization setting, but it slows things`
			`down.</dd>`

			`<dt><tt>--enable-debug-symbols</tt></dt><dd>Builds LLVM with <tt>-g</tt>.`
			`Also available by setting <tt>DEBUG_SYMBOLS=0\|1</tt> in <tt>make</tt>'s`
			`environment. This defaults to disabled when optimizing, so you should turn it`
			`back on to let users debug their programs.</dd>`

			`<dt><tt>--enable-optimized</tt></dt><dd>(For svn checkouts) Builds LLVM with`
			`<tt>-O2</tt> and, by default, turns off debug symbols. Also available by`
			`setting <tt>ENABLE_OPTIMIZED=0\|1</tt> in <tt>make</tt>'s environment. This`
			`defaults to enabled when not in a checkout.</dd>`
			`</dl>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`</div>`

			`<!--=========================================================================-->`
docs: Use <Hn> as Heading elements instead of <DIV class="doc_foo">. H1 ... doc_title H2 ... doc_section H3 ... doc_subsection H4 ... doc_subsubsection llvm-svn: 129736 2011-04-19 01:59:50 +02:00			`<h2><a name="cxx-features">C++ Features</a></h2>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<!--=========================================================================-->`
docs: Introduce cascading style <div> and <p> continued on <h[2-5]>. <h2>Section Example</h2> <div> <!-- h2+div is applied --> <p>Section preamble.</p> <h3>Subsection Example</h3> <p> <!-- h3+p is applied --> Subsection body </p> <!-- End of section body --> </div> FIXME: Care H5 better. llvm-svn: 130040 2011-04-23 02:30:22 +02:00			`<div>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00
			`<dl>`
			`<dt>RTTI</dt><dd>LLVM disables RTTI by default. Add <tt>REQUIRES_RTTI=1</tt>`
			`to your environment while running <tt>make</tt> to re-enable it. This will`
Remove REQUIRES_EH from the suggested set of make variables, since users can build with exceptions even if LLVM is built without. llvm-svn: 97260 2010-02-26 21:43:33 +01:00			`allow users to build with RTTI enabled and still inherit from LLVM`
			`classes.</dd>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`</dl>`
			`</div>`

			`<!--=========================================================================-->`
docs: Use <Hn> as Heading elements instead of <DIV class="doc_foo">. H1 ... doc_title H2 ... doc_section H3 ... doc_subsection H4 ... doc_subsubsection llvm-svn: 129736 2011-04-19 01:59:50 +02:00			`<h2><a name="shared-library">Shared Library</a></h2>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<!--=========================================================================-->`
docs: Introduce cascading style <div> and <p> continued on <h[2-5]>. <h2>Section Example</h2> <div> <!-- h2+div is applied --> <p>Section preamble.</p> <h3>Subsection Example</h3> <p> <!-- h3+p is applied --> Subsection body </p> <!-- End of section body --> </div> FIXME: Care H5 better. llvm-svn: 130040 2011-04-23 02:30:22 +02:00			`<div>`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00
			`<p>Configure with <tt>--enable-shared</tt> to build`
			`<tt>libLLVM-<var>major</var>.<var>minor</var>.(so\|dylib)</tt> and link the tools`
			`against it. This saves lots of binary size at the cost of some startup time.`
			`</p>`
			`</div>`

Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00			`<!--=========================================================================-->`
docs: Use <Hn> as Heading elements instead of <DIV class="doc_foo">. H1 ... doc_title H2 ... doc_section H3 ... doc_subsection H4 ... doc_subsubsection llvm-svn: 129736 2011-04-19 01:59:50 +02:00			`<h2><a name="deps">Dependencies</a></h2>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00			`<!--=========================================================================-->`
docs: Introduce cascading style <div> and <p> continued on <h[2-5]>. <h2>Section Example</h2> <div> <!-- h2+div is applied --> <p>Section preamble.</p> <h3>Subsection Example</h3> <p> <!-- h3+p is applied --> Subsection body </p> <!-- End of section body --> </div> FIXME: Care H5 better. llvm-svn: 130040 2011-04-23 02:30:22 +02:00			`<div>`
Add to the packaging advice. llvm-svn: 97229 2010-02-26 19:03:43 +01:00
			`<dl>`
			`<dt><tt>--enable-libffi</tt></dt><dd>Depend on <a`
			`href="http://sources.redhat.com/libffi/">libffi</a> to allow the LLVM`
			`interpreter to call external functions.</dd>`
			`<dt><tt>--with-oprofile</tt></dt><dd>Depend on <a`
			`href="http://oprofile.sourceforge.net/doc/devel/index.html">libopagent</a>`
			`(>=version 0.9.4) to let the LLVM JIT tell oprofile about function addresses and`
			`line numbers.</dd>`
			`</dl>`
			`</div>`

Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`<!-- *********************************************************************** -->`
			`<hr>`
			`<address>`
			`<a href="http://jigsaw.w3.org/css-validator/check/referer"><img`
			`src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>`
			`<a href="http://validator.w3.org/check/referer"><img`
			`src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>`
docs: Canonicalize URLs. llvm-svn: 129181 2011-04-09 04:13:37 +02:00			`<a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>`
Set svn:keywords property on docs/Packaging.html. llvm-svn: 97230 2010-02-26 19:07:00 +01:00			`Last modified: $Date$`
Give packagers some advice about how to build LLVM so it's useful to the most users. llvm-svn: 97198 2010-02-26 01:54:42 +01:00			`</address>`
			`</body>`
			`</html>`