Installation and configuration

| Home | Libraries | People | FAQ | More

## Installation and configuration

This section provides some guidelines on how to install and configure BoostBook and Quickbook under several operating systems.

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.

### Mac OS X

> Section contributed by Julio M. Merino Vidal

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.

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.

Mac OS X 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:

1. Download Docbook XML 4.2 and unpack it inside `/usr/local/share/xml/docbook/4.2`.
2. Download the latest Docbook XSL version and unpack it. Put the results in `/usr/local/share/xsl/docbook`, thus effectively removing the version number from the directory name (for simplicity).
3. 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:

1. Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
2. Build the utility by issuing `bjam --v2`.
3. Copy the resulting `quickbook` binary (located under the `BOOST_ROOT/bin.v2` hierarchy) to a safe place. Following our previous example, you can install it into: `/usr/local/bin`.
4. Add the following to your `user-config.jam` file:

    using quickbook
        : "/usr/local/bin/quickbook" ;
        ;

Additionally, if you need to build documentation that uses Doxygen, you will need to install it too:

1. Go to the downloads section and get the disk image (`dmg` file) for Mac OS X.
2. Open the disk image and drag the Doxygen application to your `Applications` folder to install it.
3. Add the following to your `user-config.jam` file:

    using doxygen
        : /Applications/Doxygen.app/Contents/Resources/doxygen
        ;

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 pkgsrc.

### Windows 2000, XP, 2003, Vista

> 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 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.

1. 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 binary packages made by Igor Zlatkovic. At the very least, you need to download the following packages: `iconv`, `zlib`, `libxml2` and `libxslt`.
2. 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.
3. From the command line, go to the `bin` directory and launch `xsltproc.exe` to ensure it works. You should get usage information on screen.
4. Download Docbook XML 4.2 and unpack it in the same directory used above. That is: `C:\Users\example\Documents\boost\xml\docbook-xml`.
5. Download the latest Docbook XSL version and unpack it, again in the same directory used before. 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`.
6. 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:

1. Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).
2. Build the utility by issuing `bjam --v2`.
3. Copy the resulting `quickbook.exe` binary (located under the `BOOST_ROOT\bin.v2` hierarchy) to a safe place. Following our previous example, you can install it into: `C:\Users\example\Documents\boost\xml\bin`.
4. Add the following to your `user-config.jam` file:

    using quickbook
        : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
        ;

### 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.

First install the `bjam`, `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 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:

1. Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).
2. Build the utility by issuing `bjam --v2`.
3. Copy the resulting `quickbook` binary (located under the `BOOST_ROOT/bin.v2` hierarchy) to a safe place. The traditional location is `/usr/local/bin`.
4. Add the following to your `user-config.jam` file, using the full path of the quickbook executable:

    using quickbook
        : /usr/local/bin/quickbook
        ;