251 lines
7.9 KiB
Plaintext
251 lines
7.9 KiB
Plaintext
[/
|
|
Copyright 2013-2018 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 Installing Boostbook and Quickbook
|
|
[id boost_doc_tools.install]
|
|
[quickbook 1.5]
|
|
[source-mode teletype]
|
|
]
|
|
|
|
[section:intro Introduction]
|
|
|
|
This chapter describes how to install the basic documentation tools that make
|
|
up the Boost documentation toolchain. This isn't enough for building the full
|
|
Boost documentation, but it's enough to start using quickbook or boostbook.
|
|
The basic requirements are:
|
|
|
|
* Boost Build
|
|
* `xsltproc`, which is a part of [@http://xmlsoft.org/XSLT/ `libxslt`].
|
|
* [@http://docbook.sourceforge.net/ Norman Walsh's DocBook XSL
|
|
stylesheets] - Note that sourceforge has organized these files so that
|
|
the documentation for the stylesheets is the first set of files
|
|
offered for download; you have to look farther down for the actual
|
|
stylesheets.
|
|
* [@http://www.oasis-open.org/docbook/xml/4.2/ The DocBook DTD]
|
|
|
|
Installing all of these parts can be quite tricky, so the next section
|
|
contains recipes to set them up for [link install_windows Windows],
|
|
[link install_mac OS X], [link install_debian Debian and Ubuntu].
|
|
Other configurations are of course possible, but we've found these ones
|
|
effective.
|
|
|
|
They assume that you have already installed Boost.Build and are familiar with
|
|
the basics of using it, see [@boost:/more/getting_started/index.html the
|
|
getting started guide] for an introduction. It's generally a good idea to
|
|
install Boost.Build from source, the prebuilt packages are often out of date.
|
|
|
|
[endsect]
|
|
|
|
[section:recipes Installation Recipes]
|
|
|
|
[#install_windows]
|
|
[section:windows Windows]
|
|
|
|
Since most of these command line tools were developed for Unix, and Unix style,
|
|
platforms they are an awkward fit for windows and recipes requires more effort.
|
|
This leads to two possible techniques, firstly install with cygwin which
|
|
handles much of the complexity for you, but requires that you always use it
|
|
from within Cygwin. The other is to manually install the toolchain for use from
|
|
the windows command prompt. This gives a more integrated user experience but is
|
|
quite fiddly to get right.
|
|
|
|
[section:cygwin Cygwin Install]
|
|
|
|
These instruction assume that cygwin has been installed to [^c:\\cygwin].
|
|
|
|
Install these packages:
|
|
|
|
* [^ Libs/libxml2]
|
|
* [^ Libs/libxslt]
|
|
* [^ Text/docbook-xml42]
|
|
* [^ Text/docbook-xsl]
|
|
* [^ Devel/gcc4-g++] (optional, if you don't have a compiler).
|
|
* [^ Devel/doxygen] (optional, for generating reference documentation
|
|
from C++ source files).
|
|
|
|
Now we need to configure Boost.Build to use these tools. This step is different
|
|
depending on whether you're using Boost.Build built with cygwin, or for native
|
|
windows. For cygwin you need to add to your `user-config.jam` file:
|
|
|
|
using xsltproc ;
|
|
|
|
using boostbook
|
|
: /usr/share/docbook-xsl
|
|
: /usr/share/xml/docbook/4.2
|
|
;
|
|
|
|
using quickbook ;
|
|
|
|
# If you installed doxygen:
|
|
using doxygen ;
|
|
|
|
When using a native (non-Cygwin) Boost.Build, you'll need to specify the
|
|
windows paths to the various tools:
|
|
|
|
# Adjust this path to the location of your cygwin install.
|
|
CYGWIN_DIR = c:/cygwin ;
|
|
|
|
using xsltproc
|
|
: $(CYGWIN_DIR)/bin/xsltproc.exe ;
|
|
|
|
using boostbook
|
|
: $(CYGWIN_DIR)/usr/share/docbook-xsl
|
|
: $(CYGWIN_DIR)/usr/share/xml/docbook/4.2
|
|
;
|
|
|
|
using quickbook ;
|
|
|
|
# If you installed doxygen:
|
|
using doxygen
|
|
: $(CYGWIN_DIR)/bin/doxygen.exe
|
|
;
|
|
|
|
[endsect] [/ cygwin ]
|
|
|
|
[section:manual Manually installing windows native tools]
|
|
|
|
In order to install the tools under windows, we need to create a directory
|
|
structure somewhat similar to the unix filesystem. We're going to place this
|
|
in [^c:\\boost-tools], if you want to put it elsewhere, just follow the
|
|
instructions, adjusting the paths accordingly. This is also a good location
|
|
to use as the prefix when installing Boost.Build.
|
|
|
|
* Create directory for boost tools, say [^ c:\\boost-tools].
|
|
* Create directory for binaries, [^ c:\\boost-tools\\bin].
|
|
* Add the [^bin] directory to the path (e.g. in Xp, right click on 'My
|
|
Computer', click on 'Properties', then the 'Advanced' tab and click on
|
|
'Environment variables' to open a dialog where you can edit the PATH
|
|
variable).
|
|
|
|
Next you need to download several xml tools from
|
|
[@http://www.zlatkovic.com/pub/libxml/ Igor Zlatkovic].
|
|
You require: [^ iconv], [^ libxml2] and [^ libxslt], [^ zlib].
|
|
Then unzip these into the [^c:\\boost-tools] directory.
|
|
This should place the `xsltproc` exectuable in [^c:\\boost-tools\\bin].
|
|
|
|
Next make a directory for xml processing files at [^ c:\\boost-tools\\xml].
|
|
|
|
* [@http://docbook.sourceforge.net/ Norman Walsh's DocBook XSL
|
|
stylesheets] from their
|
|
[@http://sourceforge.net/project/showfiles.php?group_id=21935&
|
|
package_id=16608 Sourceforge download page] to
|
|
[^ c:\\boost-tools\\xml\\docbook-xsl].
|
|
* [@http://www.oasis-open.org/docbook/xml/4.2/ The DocBook DTD] to
|
|
[^ c:\\boost-tools\\xml\\docbook-xml].
|
|
|
|
[^ user-config.jam] in the boost build search path,
|
|
for most people this will be [^ C:\\Documents and Settings\\['username]].
|
|
|
|
BOOST_TOOLS_DIR = c:/boost-tools ;
|
|
using xsltproc
|
|
: $(BOOST_TOOLS_DIR)/bin/xsltproc.exe"
|
|
;
|
|
|
|
using boostbook
|
|
: $(BOOST_TOOLS_DIR)/xml/docbook-xsl
|
|
: $(BOOST_TOOLS_DIR)/xml/docbook-xml
|
|
;
|
|
|
|
using quickbook ;
|
|
|
|
Also, if you wish to use doxygen to generate reference documentation from
|
|
C++ source headers, you'll need to install it. You can download it from
|
|
[@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc the doxygen
|
|
website]. The installer should add the executable to your path, so you just
|
|
need to add to your [^ user-config.jam]:
|
|
|
|
using doxygen ;
|
|
|
|
[endsect] [/ manual ]
|
|
|
|
[endsect] [/ windows ]
|
|
|
|
[#install_mac]
|
|
[section:mac OS X]
|
|
|
|
If you're using Snow Leopard (OS X 10.6) or later, then you should already have
|
|
the xml tools installed, so you just need to install the docbook xml and xslt
|
|
files. The easiest way to do that is probably to use macports, install them
|
|
with:
|
|
|
|
sudo port install docbook-xml-4.2 docbook-xsl
|
|
|
|
For earlier versions of OS X, you'll also need to install `libxslt` to get
|
|
an up to date version of `xsltproc`:
|
|
|
|
sudo port install libxslt docbook-xml-4.2 docbook-xsl
|
|
|
|
You can also install `doxygen`, for generating reference documentation from
|
|
C++ source files:
|
|
|
|
sudo port install doxygen
|
|
|
|
Boost.Build knows the default install location for macports, so all you need
|
|
to add to your `user-config.jam` is an instruction to use them:
|
|
|
|
using boostbook ;
|
|
using quickbook ;
|
|
|
|
# If you've installed doxygen:
|
|
using doxygen ;
|
|
|
|
[endsect] [/ mac]
|
|
|
|
[#install_debian]
|
|
[section:debian Debian and Ubuntu]
|
|
|
|
Installing on Debian and Ubuntu is pretty easy, just install the packages using
|
|
`apt-get` (or an alternative, such as `aptitude`):
|
|
|
|
sudo apt-get install xsltproc docbook-xsl docbook-xml
|
|
|
|
You can also install `doxygen`, for generating reference documentation from
|
|
C++ source files:
|
|
|
|
sudo apt-get install doxygen
|
|
|
|
Boost.Build should be to find these packages without an explicit path, so just
|
|
add to your `user-config.jam`:
|
|
|
|
using boostbook ;
|
|
using quickbook ;
|
|
|
|
# If you've installed doxygen:
|
|
using doxygen ;
|
|
|
|
[endsect] [/ debian]
|
|
|
|
[endsect]
|
|
|
|
[section:quickbook Pre-build quickbook]
|
|
|
|
Boost.Build automatically builds Quickbook when required to build the
|
|
documentation, but as it
|
|
takes a little while to build you might prefer to build it in advance.
|
|
To do this, in the command line type (replacing [^$BOOST_ROOT] with the
|
|
root directory of boost):
|
|
|
|
cd $BOOST_ROOT/tools/quickbook
|
|
b2 dist-bin
|
|
|
|
Or for windows:
|
|
|
|
cd $BOOST_ROOT\\tools\\quickbook
|
|
b2 dist-bin
|
|
|
|
Change [^ using quickbook] in [^ user-config.jam] to (replacing [^
|
|
$BOOST_ROOT] with the root directory of boost, as before):
|
|
|
|
using quickbook : $BOOST_ROOT/dist/bin/quickbook ;
|
|
|
|
Windows:
|
|
|
|
using quickbook : $BOOST_ROOT\\dist\\bin\\quickbook ;
|
|
|
|
[endsect] [/quickbook]
|