318 lines
11 KiB
Plaintext
318 lines
11 KiB
Plaintext
[/
|
|
Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
|
|
Copyright 2010-2011 Daniel James
|
|
|
|
Distributed under the Boost Software License, Version 1.0.
|
|
(See accompanying file LICENSE_1_0.txt or copy at
|
|
http://www.boost.org/LICENSE_1_0.txt)
|
|
]
|
|
|
|
[chapter Installation and configuration
|
|
[quickbook 1.7]
|
|
[compatibility-mode 1.5]
|
|
[id quickbook.install]
|
|
[source-mode teletype]
|
|
]
|
|
|
|
This section provides some guidelines on how to install and configure
|
|
BoostBook and Quickbook under several operating systems. Before installing
|
|
you'll need a local copy of boost, and to install the version of `bjam`
|
|
which comes with it (or a later version).
|
|
|
|
[/ I don't think this is needed any more]
|
|
[/
|
|
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 `bin` and `bin.v2` directories generated
|
|
by the build before trying again. Otherwise your configuration fixes will
|
|
not take any effect.
|
|
]
|
|
|
|
[section:macosx Mac OS X]
|
|
|
|
The simplest way to install on OS X is to use macports.
|
|
If you don't want to use macports and are using Snow Leopard or later,
|
|
there are instructions [link quickbook.install.macosx.native later].
|
|
Earlier versions of OS X need to use something like macports to install
|
|
`xsltproc` because the version they come with is very old, and doesn't have
|
|
good enough XSL support for boostbook's stylesheets.
|
|
|
|
[section:macports Mac OS X, using macports]
|
|
|
|
First install the `libxslt`, `docbook-xsl` and `docbook-xml-4.2`
|
|
packages:
|
|
|
|
sudo port install libxslt docbook-xsl docbook-xml-4.2
|
|
|
|
Next, we need to configure Boost Build to compile BoostBook files. Add the
|
|
following to your `user-config.jam` 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 `user-config.jam`, see the
|
|
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
|
|
Build documentation].
|
|
|
|
using xsltproc
|
|
: /opt/local/bin/xsltproc
|
|
;
|
|
|
|
using boostbook
|
|
: /opt/local/share/xsl/docbook-xsl/
|
|
: /opt/local/share/xml/docbook/4.2
|
|
;
|
|
|
|
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:
|
|
|
|
# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
|
|
|
|
# Build the utility by issuing `bjam`.
|
|
|
|
# Copy the resulting `quickbook` binary (located at
|
|
`BOOST_ROOT/dist/bin`) to a safe place. The traditional location is
|
|
`/usr/local/bin`.
|
|
|
|
# Add the following to your `user-config.jam` file, using the full path of the
|
|
quickbook executable:
|
|
```
|
|
using quickbook
|
|
: /usr/local/bin/quickbook
|
|
;
|
|
```
|
|
|
|
If you need to build documentation that uses Doxygen, you will need to install it as well:
|
|
|
|
sudo port install doxygen
|
|
|
|
And then add to your `user-config.jam`:
|
|
|
|
using doxygen ;
|
|
|
|
Alternatively, you can install from the official doxygen `dmg`.
|
|
This is described at [link osx-prebuilt-doxygen the end of the next section].
|
|
|
|
[endsect:macports]
|
|
|
|
[section:native Mac OS X, Snow Leopard (or later)]
|
|
|
|
[:['Section contributed by Julio M. Merino Vidal]]
|
|
|
|
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 `/usr/local` hierarchy. If
|
|
you do not want this, you can choose any other prefix such as
|
|
`~/Applications` for a single-user installation.
|
|
|
|
Snow Leopard comes with `xsltproc` 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.
|
|
|
|
To get started:
|
|
|
|
# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
|
|
4.2] and unpack it inside `/usr/local/share/xml/docbook/4.2`.
|
|
|
|
# Download the latest
|
|
[@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
|
|
Docbook XSL] version and unpack it. Be careful that you download the correct
|
|
file, sometimes the 'looking for the latest version' link often links to
|
|
another file. The name should be of the form
|
|
'''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''',
|
|
with no suffix such as `-ns.tar.bz2` or `-doc.tar.bz2`.
|
|
Put the results in
|
|
`/usr/local/share/xsl/docbook`, thus effectively removing the version
|
|
number from the directory name (for simplicity).
|
|
|
|
# Add the following to your `user-config.jam` file, which should live in
|
|
your home directory (`/Users/<your_username>`). You must already have it
|
|
somewhere or otherwise you could not be building Boost (i.e. missing
|
|
tools configuration).
|
|
```
|
|
using xsltproc ;
|
|
|
|
using boostbook
|
|
: "/usr/local/share/xsl/docbook"
|
|
: "/usr/local/share/xml/docbook/4.2"
|
|
;
|
|
```
|
|
|
|
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:
|
|
|
|
# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
|
|
|
|
# Build the utility by issuing `bjam`.
|
|
|
|
# Copy the resulting `quickbook` binary (located at
|
|
`BOOST_ROOT/dist/bin`) to a safe place. Following our previous
|
|
example, you can install it into: `/usr/local/bin`.
|
|
|
|
# Add the following to your `user-config.jam` file:
|
|
```
|
|
using quickbook
|
|
: "/usr/local/bin/quickbook" ;
|
|
;
|
|
```
|
|
|
|
[# osx-prebuilt-doxygen]
|
|
Additionally, if you need to build documentation that uses
|
|
[@http://www.doxygen.org Doxygen], you will need to install it too:
|
|
|
|
# Go to the [@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
|
|
downloads section] and get the disk image (`dmg` file) for Mac OS X.
|
|
|
|
# Open the disk image and drag the Doxygen application to your
|
|
`Applications` folder to install it.
|
|
|
|
# Add the following to your `user-config.jam` file:
|
|
```
|
|
using doxygen
|
|
: /Applications/Doxygen.app/Contents/Resources/doxygen
|
|
;
|
|
```
|
|
|
|
[/ Removed this, since there are macports based instructions earlier.
|
|
Instructions for pkgsrc welcome]
|
|
[/
|
|
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 [@http://www.pkgsrc.org pkgsrc].
|
|
]
|
|
|
|
[endsect:native]
|
|
|
|
[endsect:macosx]
|
|
|
|
[section:windows Windows 2000, XP, 2003, Vista, 7]
|
|
|
|
[:['Section contributed by Julio M. Merino Vidal]]
|
|
|
|
The following instructions apply to any Windows system based on Windows
|
|
2000, including Windows XP, Windows 2003 Server, Windows Vista, and Windows 7. 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.
|
|
|
|
# First of all you need to have a copy of `xsltproc` for Windows. There
|
|
are many ways to get this tool, but to keep things simple, use the
|
|
[@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
|
|
Zlatkovic. At the very least, you need to download the following
|
|
packages: `iconv`, `zlib`, `libxml2` and `libxslt`.
|
|
|
|
# Unpack all these packages in the same directory so that you get unique
|
|
`bin`, `include` and `lib` directories within the hierarchy. These
|
|
instructions use `C:\Users\example\Documents\boost\xml` as the root for
|
|
all files.
|
|
|
|
# From the command line, go to the `bin` directory and launch
|
|
`xsltproc.exe` to ensure it works. You should get usage information on
|
|
screen.
|
|
|
|
# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
|
|
4.2] and unpack it in the same directory used above. That is:
|
|
`C:\Users\example\Documents\boost\xml\docbook-xml`.
|
|
|
|
# Download the latest
|
|
[@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
|
|
Docbook XSL] version and unpack it, again in the same directory
|
|
used before. Be careful that you download the correct
|
|
file, sometimes the 'looking for the latest version' link often links to
|
|
another file. The name should be of the form
|
|
'''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''',
|
|
with no suffix such as `-ns.tar.bz2` or `-doc.tar.bz2`.
|
|
To make things easier, rename the directory created
|
|
during the extraction to `docbook-xsl` (bypassing the version name):
|
|
`C:\Users\example\Documents\boost\xml\docbook-xsl`.
|
|
|
|
# Add the following to your `user-config.jam` file, which should live in
|
|
your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it
|
|
somewhere or otherwise you could not be building Boost (i.e. missing
|
|
tools configuration).
|
|
```
|
|
using xsltproc
|
|
: "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
|
|
;
|
|
|
|
using boostbook
|
|
: "C:/Users/example/Documents/boost/xml/docbook-xsl"
|
|
: "C:/Users/example/Documents/boost/xml/docbook-xml"
|
|
;
|
|
```
|
|
|
|
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:
|
|
|
|
# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).
|
|
|
|
# Build the utility by issuing `bjam`.
|
|
|
|
# Copy the resulting `quickbook.exe` binary (located at
|
|
`BOOST_ROOT\dist\bin`) to a safe place. Following our previous
|
|
example, you can install it into:
|
|
`C:\Users\example\Documents\boost\xml\bin`.
|
|
|
|
# Add the following to your `user-config.jam` file:
|
|
```
|
|
using quickbook
|
|
: "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
|
|
;
|
|
```
|
|
|
|
[endsect:windows]
|
|
|
|
[section:linux Debian, Ubuntu]
|
|
|
|
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. They
|
|
assume you've already installed an appropriate version of `bjam` for your
|
|
copy of boost.
|
|
|
|
First install the `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
|
|
For example, using `apt-get`:
|
|
|
|
sudo apt-get install xsltproc docbook-xsl docbook-xml
|
|
|
|
If you're planning on building boost's documentation, you'll also need to
|
|
install the `doxygen` package as well.
|
|
|
|
Next, we need to configure Boost Build to compile BoostBook files. Add the
|
|
following to your `user-config.jam` 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 `user-config.jam`, see the
|
|
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
|
|
Build documentation].
|
|
|
|
using xsltproc ;
|
|
|
|
using boostbook
|
|
: /usr/share/xml/docbook/stylesheet/nwalsh
|
|
: /usr/share/xml/docbook/schema/dtd/4.2
|
|
;
|
|
|
|
# Remove this line if you're not using doxygen
|
|
using doxygen ;
|
|
|
|
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:
|
|
|
|
# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
|
|
|
|
# Build the utility by issuing `bjam`.
|
|
|
|
# Copy the resulting `quickbook` binary (located at
|
|
`BOOST_ROOT/dist/bin`) to a safe place. The traditional location is
|
|
`/usr/local/bin`.
|
|
|
|
# Add the following to your `user-config.jam` file, using the full path of the
|
|
quickbook executable:
|
|
```
|
|
using quickbook
|
|
: /usr/local/bin/quickbook
|
|
;
|
|
```
|
|
|
|
[endsect:linux]
|