<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Installation and configuration</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../quickbook.html" title="Chapter 31. Quickbook 1.5">
<link rel="prev" href="syntax.html" title="Syntax Summary">
<link rel="next" href="editors.html" title="Editor Support">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="syntax.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="editors.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="quickbook.install"></a><a class="link" href="install.html" title="Installation and configuration"> Installation and configuration</a>
</h2></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="install.html#quickbook.install.macosx"> Mac OS X</a></span></dt>
<dt><span class="section"><a href="install.html#quickbook.install.windows"> Windows 2000, XP, 2003, Vista</a></span></dt>
<dt><span class="section"><a href="install.html#quickbook.install.linux"> Debian, Ubuntu</a></span></dt>
</dl></div>
<p>
This section provides some guidelines on how to install and configure BoostBook
and Quickbook under several operating systems.
</p>
<p>
Before continuing, it is very important that you keep this in mind: if you
try to build some documents and the process breaks due to misconfiguration,
be absolutely sure to delete any <code class="computeroutput"><span class="identifier">bin</span></code>
and <code class="computeroutput"><span class="identifier">bin</span><span class="special">.</span><span class="identifier">v2</span></code> directories generated by the build before
trying again. Otherwise your configuration fixes will not take any effect.
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.install.macosx"></a><a class="link" href="install.html#quickbook.install.macosx" title="Mac OS X"> Mac OS X</a>
</h3></div></div></div>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>Section contributed by Julio M. Merino Vidal</em></span>
</p></blockquote></div>
<p>
The following instructions explain how to install Docbook XML, Docbook XSL
and Doxygen in a Mac OS X system, how to configure Boost.Build v2 to recognize
them and how to build and install Quickbook. They were taken from a 10.4
(Tiger) machine so it is likely that they also apply to future versions;
they may not work with older ones, though.
</p>
<p>
The text below assumes you want to install all the necessary utilities in
a system-wide location, allowing any user in the machine to have access to
them. Therefore, all files will be put in the <code class="computeroutput"><span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span></code>
hierarchy. If you do not want this, you can choose any other prefix such
as <code class="computeroutput"><span class="special">~/</span><span class="identifier">Applications</span></code>
for a single-user installation.
</p>
<p>
Mac OS X comes with <code class="computeroutput"><span class="identifier">xsltproc</span></code>
and all related libraries preinstalled, so you do not need to take any extra
steps to set them up. It is probable that future versions will include them
too, but these instructions may not apply to older versions.
</p>
<p>
To get started:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Download <a href="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip" target="_top">Docbook
XML 4.2</a> and unpack it inside <code class="computeroutput"><span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="number">4.2</span></code>.
</li>
<li class="listitem">
Download the latest <a href="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608" target="_top">Docbook
XSL</a> version and unpack it. Put the results in <code class="computeroutput"><span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xsl</span><span class="special">/</span><span class="identifier">docbook</span></code>, thus effectively removing
the version number from the directory name (for simplicity).
</li>
<li class="listitem">
Add the following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
file, which should live in your home directory (<code class="computeroutput"><span class="special">/</span><span class="identifier">Users</span><span class="special">/<</span><span class="identifier">your_username</span><span class="special">></span></code>).
You must already have it somewhere or otherwise you could not be building
Boost (i.e. missing tools configuration).
</li>
</ol></div>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">xsltproc</span> <span class="special">;</span>
<span class="keyword">using</span> <span class="identifier">boostbook</span>
<span class="special">:</span> <span class="string">"/usr/local/share/xsl/docbook"</span>
<span class="special">:</span> <span class="string">"/usr/local/share/xml/docbook/4.2"</span>
<span class="special">;</span>
</pre>
<p>
The above steps are enough to get a functional BoostBook setup. Quickbook
will be automatically built when needed. If you want to avoid these rebuilds
and install a system-wide Quickbook instead:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Go to Quickbook's source directory (<code class="computeroutput"><span class="identifier">BOOST_ROOT</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">quickbook</span></code>).
</li>
<li class="listitem">
Build the utility by issuing <code class="computeroutput"><span class="identifier">bjam</span></code>.
</li>
<li class="listitem">
Copy the resulting <code class="computeroutput"><span class="identifier">quickbook</span></code>
binary (located under the <code class="computeroutput"><span class="identifier">BOOST_ROOT</span><span class="special">/</span><span class="identifier">bin</span><span class="special">.</span><span class="identifier">v2</span></code>
hierarchy) to a safe place. Following our previous example, you can install
it into: <code class="computeroutput"><span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">bin</span></code>.
</li>
<li class="listitem">
Add the following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
file:
</li>
</ol></div>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">quickbook</span>
<span class="special">:</span> <span class="string">"/usr/local/bin/quickbook"</span> <span class="special">;</span>
<span class="special">;</span>
</pre>
<p>
Additionally, if you need to build documentation that uses <a href="http://www.doxygen.org" target="_top">Doxygen</a>,
you will need to install it too:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Go to the <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc" target="_top">downloads
section</a> and get the disk image (<code class="computeroutput"><span class="identifier">dmg</span></code>
file) for Mac OS X.
</li>
<li class="listitem">
Open the disk image and drag the Doxygen application to your <code class="computeroutput"><span class="identifier">Applications</span></code> folder to install it.
</li>
<li class="listitem">
Add the following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
file:
</li>
</ol></div>
<pre class="programlisting"><span class="keyword">using</span> <span class="identifier">doxygen</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">Applications</span><span class="special">/</span><span class="identifier">Doxygen</span><span class="special">.</span><span class="identifier">app</span><span class="special">/</span><span class="identifier">Contents</span><span class="special">/</span><span class="identifier">Resources</span><span class="special">/</span><span class="identifier">doxygen</span>
<span class="special">;</span>
</pre>
<p>
Alternatively, you may want to install all the prerequistes through a package
system to avoid manual management of the installations. In that case, check
out <a href="http://www.pkgsrc.org" target="_top">pkgsrc</a>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.install.windows"></a><a class="link" href="install.html#quickbook.install.windows" title="Windows 2000, XP, 2003, Vista"> Windows 2000, XP, 2003, Vista</a>
</h3></div></div></div>
<p>
</p>
<div class="blockquote"><blockquote class="blockquote"><p>
<span class="emphasis"><em>Section contributed by Julio M. Merino Vidal</em></span>
</p></blockquote></div>
<p>
The following instructions apply to any Windows system based on Windows 2000,
including Windows XP, Windows 2003 Server and Windows Vista. The paths shown
below are taken from a Windows Vista machine; you will need to adjust them
to match your system in case you are running an older version.
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
First of all you need to have a copy of <code class="computeroutput"><span class="identifier">xsltproc</span></code>
for Windows. There are many ways to get this tool, but to keep things
simple, use the <a href="http://www.zlatkovic.com/pub/libxml/" target="_top">binary
packages</a> made by Igor Zlatkovic. At the very least, you need
to download the following packages: <code class="computeroutput"><span class="identifier">iconv</span></code>,
<code class="computeroutput"><span class="identifier">zlib</span></code>, <code class="computeroutput"><span class="identifier">libxml2</span></code>
and <code class="computeroutput"><span class="identifier">libxslt</span></code>.
</li>
<li class="listitem">
Unpack all these packages in the same directory so that you get unique
<code class="computeroutput"><span class="identifier">bin</span></code>, <code class="computeroutput"><span class="identifier">include</span></code>
and <code class="computeroutput"><span class="identifier">lib</span></code> directories within
the hierarchy. These instructions use <code class="computeroutput"><span class="identifier">C</span><span class="special">:\</span><span class="identifier">Users</span><span class="special">\</span><span class="identifier">example</span><span class="special">\</span><span class="identifier">Documents</span><span class="special">\</span><span class="identifier">boost</span><span class="special">\</span><span class="identifier">xml</span></code>
as the root for all files.
</li>
<li class="listitem">
From the command line, go to the <code class="computeroutput"><span class="identifier">bin</span></code>
directory and launch <code class="computeroutput"><span class="identifier">xsltproc</span><span class="special">.</span><span class="identifier">exe</span></code>
to ensure it works. You should get usage information on screen.
</li>
<li class="listitem">
Download <a href="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip" target="_top">Docbook
XML 4.2</a> and unpack it in the same directory used above. That
is: <code class="computeroutput"><span class="identifier">C</span><span class="special">:\</span><span class="identifier">Users</span><span class="special">\</span><span class="identifier">example</span><span class="special">\</span><span class="identifier">Documents</span><span class="special">\</span><span class="identifier">boost</span><span class="special">\</span><span class="identifier">xml</span><span class="special">\</span><span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xml</span></code>.
</li>
<li class="listitem">
Download the latest <a href="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608" target="_top">Docbook
XSL</a> version and unpack it, again in the same directory used before.
To make things easier, rename the directory created during the extraction
to <code class="computeroutput"><span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xsl</span></code> (bypassing the version name):
<code class="computeroutput"><span class="identifier">C</span><span class="special">:\</span><span class="identifier">Users</span><span class="special">\</span><span class="identifier">example</span><span class="special">\</span><span class="identifier">Documents</span><span class="special">\</span><span class="identifier">boost</span><span class="special">\</span><span class="identifier">xml</span><span class="special">\</span><span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xsl</span></code>.
</li>
<li class="listitem">
Add the following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
file, which should live in your home directory (<code class="computeroutput"><span class="special">%</span><span class="identifier">HOMEDRIVE</span><span class="special">%%</span><span class="identifier">HOMEPATH</span><span class="special">%</span></code>).
You must already have it somewhere or otherwise you could not be building
Boost (i.e. missing tools configuration).
</li>
</ol></div>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">xsltproc</span>
<span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"</span>
<span class="special">;</span>
<span class="identifier">using</span> <span class="identifier">boostbook</span>
<span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/docbook-xsl"</span>
<span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/docbook-xml"</span>
<span class="special">;</span>
</pre>
<p>
The above steps are enough to get a functional BoostBook setup. Quickbook
will be automatically built when needed. If you want to avoid these rebuilds:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Go to Quickbook's source directory (<code class="computeroutput"><span class="identifier">BOOST_ROOT</span><span class="special">\</span><span class="identifier">tools</span><span class="special">\</span><span class="identifier">quickbook</span></code>).
</li>
<li class="listitem">
Build the utility by issuing <code class="computeroutput"><span class="identifier">bjam</span></code>.
</li>
<li class="listitem">
Copy the resulting <code class="computeroutput"><span class="identifier">quickbook</span><span class="special">.</span><span class="identifier">exe</span></code>
binary (located under the <code class="computeroutput"><span class="identifier">BOOST_ROOT</span><span class="special">\</span><span class="identifier">bin</span><span class="special">.</span><span class="identifier">v2</span></code>
hierarchy) to a safe place. Following our previous example, you can install
it into: <code class="computeroutput"><span class="identifier">C</span><span class="special">:\</span><span class="identifier">Users</span><span class="special">\</span><span class="identifier">example</span><span class="special">\</span><span class="identifier">Documents</span><span class="special">\</span><span class="identifier">boost</span><span class="special">\</span><span class="identifier">xml</span><span class="special">\</span><span class="identifier">bin</span></code>.
</li>
<li class="listitem">
Add the following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
file:
</li>
</ol></div>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">quickbook</span>
<span class="special">:</span> <span class="string">"C:/Users/example/Documents/boost/xml/bin/quickbook.exe"</span>
<span class="special">;</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="quickbook.install.linux"></a><a class="link" href="install.html#quickbook.install.linux" title="Debian, Ubuntu"> Debian, Ubuntu</a>
</h3></div></div></div>
<p>
The following instructions apply to Debian and its derivatives. They are
based on a Ubuntu Edgy install but should work on other Debian based systems.
</p>
<p>
First install the <code class="computeroutput"><span class="identifier">bjam</span></code>,
<code class="computeroutput"><span class="identifier">xsltproc</span></code>, <code class="computeroutput"><span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xsl</span></code> and
<code class="computeroutput"><span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xml</span></code> packages. For example, using <code class="computeroutput"><span class="identifier">apt</span><span class="special">-</span><span class="identifier">get</span></code>:
</p>
<pre class="programlisting"><span class="identifier">sudo</span> <span class="identifier">apt</span><span class="special">-</span><span class="identifier">get</span> <span class="identifier">install</span> <span class="identifier">xsltproc</span> <span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xsl</span> <span class="identifier">docbook</span><span class="special">-</span><span class="identifier">xml</span>
</pre>
<p>
If you're planning on building boost's documentation, you'll also need to
install the <code class="computeroutput"><span class="identifier">doxygen</span></code> package
as well.
</p>
<p>
Next, we need to configure Boost Build to compile BoostBook files. Add the
following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code> file, which should be in your home
directory. If you don't have one, create a file containing this text. For
more information on setting up <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>, see
the <a href="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html" target="_top">Boost
Build documentation</a>.
</p>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">xsltproc</span> <span class="special">;</span>
<span class="identifier">using</span> <span class="identifier">boostbook</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="identifier">stylesheet</span><span class="special">/</span><span class="identifier">nwalsh</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">share</span><span class="special">/</span><span class="identifier">xml</span><span class="special">/</span><span class="identifier">docbook</span><span class="special">/</span><span class="identifier">schema</span><span class="special">/</span><span class="identifier">dtd</span><span class="special">/</span><span class="number">4.2</span>
<span class="special">;</span>
<span class="comment"># Remove this line if you're not using doxygen
</span><span class="identifier">using</span> <span class="identifier">doxygen</span> <span class="special">;</span>
</pre>
<p>
The above steps are enough to get a functional BoostBook setup. Quickbook
will be automatically built when needed. If you want to avoid these rebuilds:
</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
Go to Quickbook's source directory (<code class="computeroutput"><span class="identifier">BOOST_ROOT</span><span class="special">/</span><span class="identifier">tools</span><span class="special">/</span><span class="identifier">quickbook</span></code>).
</li>
<li class="listitem">
Build the utility by issuing <code class="computeroutput"><span class="identifier">bjam</span></code>.
</li>
<li class="listitem">
Copy the resulting <code class="computeroutput"><span class="identifier">quickbook</span></code>
binary (located under the <code class="computeroutput"><span class="identifier">BOOST_ROOT</span><span class="special">/</span><span class="identifier">bin</span><span class="special">.</span><span class="identifier">v2</span></code>
hierarchy) to a safe place. The traditional location is <code class="computeroutput"><span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">bin</span></code>.
</li>
<li class="listitem">
Add the following to your <code class="computeroutput"><span class="identifier">user</span><span class="special">-</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">jam</span></code>
file, using the full path of the quickbook executable:
</li>
</ol></div>
<pre class="programlisting"><span class="identifier">using</span> <span class="identifier">quickbook</span>
<span class="special">:</span> <span class="special">/</span><span class="identifier">usr</span><span class="special">/</span><span class="identifier">local</span><span class="special">/</span><span class="identifier">bin</span><span class="special">/</span><span class="identifier">quickbook</span>
<span class="special">;</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman,
Eric Niebler<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="syntax.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../quickbook.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="editors.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
