1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Installation and configuration</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../quickbook.html" title="Chapter 50. Quickbook 1.7"> 10<link rel="prev" href="versions.html" title="Language Versions"> 11<link rel="next" href="editors.html" title="Editor Support"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="versions.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> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="quickbook.install"></a>Installation and configuration</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="install.html#quickbook.install.macosx">Mac OS X</a></span></dt> 31<dt><span class="section"><a href="install.html#quickbook.install.windows">Windows 2000, XP, 2003, Vista, 32 7</a></span></dt> 33<dt><span class="section"><a href="install.html#quickbook.install.linux">Debian, Ubuntu</a></span></dt> 34</dl></div> 35<p> 36 This section provides some guidelines on how to install and configure BoostBook 37 and Quickbook under several operating systems. Before installing you'll need 38 a local copy of boost, and to install the version of <code class="computeroutput">bjam</code> which 39 comes with it (or a later version). 40 </p> 41<div class="section"> 42<div class="titlepage"><div><div><h3 class="title"> 43<a name="quickbook.install.macosx"></a><a class="link" href="install.html#quickbook.install.macosx" title="Mac OS X">Mac OS X</a> 44</h3></div></div></div> 45<div class="toc"><dl class="toc"> 46<dt><span class="section"><a href="install.html#quickbook.install.macosx.macports">Mac OS X, using 47 macports</a></span></dt> 48<dt><span class="section"><a href="install.html#quickbook.install.macosx.native">Mac OS X, Snow Leopard 49 (or later)</a></span></dt> 50</dl></div> 51<p> 52 The simplest way to install on OS X is to use macports. If you don't want 53 to use macports and are using Snow Leopard or later, there are instructions 54 <a class="link" href="install.html#quickbook.install.macosx.native" title="Mac OS X, Snow Leopard (or later)">later</a>. Earlier versions 55 of OS X need to use something like macports to install <code class="computeroutput">xsltproc</code> 56 because the version they come with is very old, and doesn't have good enough 57 XSL support for boostbook's stylesheets. 58 </p> 59<div class="section"> 60<div class="titlepage"><div><div><h4 class="title"> 61<a name="quickbook.install.macosx.macports"></a><a class="link" href="install.html#quickbook.install.macosx.macports" title="Mac OS X, using macports">Mac OS X, using 62 macports</a> 63</h4></div></div></div> 64<p> 65 First install the <code class="computeroutput">libxslt</code>, <code class="computeroutput">docbook-xsl</code> and <code class="computeroutput">docbook-xml-4.2</code> 66 packages: 67 </p> 68<pre class="programlisting">sudo port install libxslt docbook-xsl docbook-xml-4.2 69</pre> 70<p> 71 Next, we need to configure Boost Build to compile BoostBook files. Add 72 the following to your <code class="computeroutput">user-config.jam</code> file, which should be 73 in your home directory. If you don't have one, create a file containing 74 this text. For more information on setting up <code class="computeroutput">user-config.jam</code>, 75 see the <a href="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html" target="_top">Boost 76 Build documentation</a>. 77 </p> 78<pre class="programlisting">using xsltproc 79 : /opt/local/bin/xsltproc 80 ; 81 82using boostbook 83 : /opt/local/share/xsl/docbook-xsl/ 84 : /opt/local/share/xml/docbook/4.2 85 ; 86</pre> 87<p> 88 The above steps are enough to get a functional BoostBook setup. Quickbook 89 will be automatically built when needed. If you want to avoid these rebuilds: 90 </p> 91<div class="orderedlist"><ol class="orderedlist" type="1"> 92<li class="listitem"> 93 Go to Quickbook's source directory (<code class="computeroutput">BOOST_ROOT/tools/quickbook</code>). 94 </li> 95<li class="listitem"> 96 Build the utility by issuing <code class="computeroutput">bjam</code>. 97 </li> 98<li class="listitem"> 99 Copy the resulting <code class="computeroutput">quickbook</code> binary (located at <code class="computeroutput">BOOST_ROOT/dist/bin</code>) 100 to a safe place. The traditional location is <code class="computeroutput">/usr/local/bin</code>. 101 </li> 102<li class="listitem"> 103<p class="simpara"> 104 Add the following to your <code class="computeroutput">user-config.jam</code> file, using 105 the full path of the quickbook executable: 106 </p> 107<pre class="programlisting">using quickbook 108 : /usr/local/bin/quickbook 109 ; 110</pre> 111</li> 112</ol></div> 113<p> 114 If you need to build documentation that uses Doxygen, you will need to 115 install it as well: 116 </p> 117<pre class="programlisting">sudo port install doxygen 118</pre> 119<p> 120 And then add to your <code class="computeroutput">user-config.jam</code>: 121 </p> 122<pre class="programlisting">using doxygen ; 123</pre> 124<p> 125 Alternatively, you can install from the official doxygen <code class="computeroutput">dmg</code>. 126 This is described at <a class="link" href="install.html#osx-prebuilt-doxygen">the end of the 127 next section</a>. 128 </p> 129</div> 130<div class="section"> 131<div class="titlepage"><div><div><h4 class="title"> 132<a name="quickbook.install.macosx.native"></a><a class="link" href="install.html#quickbook.install.macosx.native" title="Mac OS X, Snow Leopard (or later)">Mac OS X, Snow Leopard 133 (or later)</a> 134</h4></div></div></div> 135<div class="blockquote"><blockquote class="blockquote"><p> 136 <span class="emphasis"><em>Section contributed by Julio M. Merino Vidal</em></span> 137 </p></blockquote></div> 138<p> 139 The text below assumes you want to install all the necessary utilities 140 in a system-wide location, allowing any user in the machine to have access 141 to them. Therefore, all files will be put in the <code class="computeroutput">/usr/local</code> 142 hierarchy. If you do not want this, you can choose any other prefix such 143 as <code class="computeroutput">~/Applications</code> for a single-user installation. 144 </p> 145<p> 146 Snow Leopard comes with <code class="computeroutput">xsltproc</code> and all related libraries 147 preinstalled, so you do not need to take any extra steps to set them up. 148 It is probable that future versions will include them too, but these instructions 149 may not apply to older versions. 150 </p> 151<p> 152 To get started: 153 </p> 154<div class="orderedlist"><ol class="orderedlist" type="1"> 155<li class="listitem"> 156 Download <a href="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip" target="_top">Docbook 157 XML 4.2</a> and unpack it inside <code class="computeroutput">/usr/local/share/xml/docbook/4.2</code>. 158 </li> 159<li class="listitem"> 160 Download the latest <a href="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608" target="_top">Docbook 161 XSL</a> version and unpack it. Be careful that you download the 162 correct file, sometimes the 'looking for the latest version' link often 163 links to another file. The name should be of the form <code class="computeroutput">docbook-xsl-1.<span class="emphasis"><em>nn</em></span>.<span class="emphasis"><em>n</em></span>.tar.bz2</code>, with no suffix 164 such as <code class="computeroutput">-ns.tar.bz2</code> or <code class="computeroutput">-doc.tar.bz2</code>. Put 165 the results in <code class="computeroutput">/usr/local/share/xsl/docbook</code>, thus effectively 166 removing the version number from the directory name (for simplicity). 167 </li> 168<li class="listitem"> 169<p class="simpara"> 170 Add the following to your <code class="computeroutput">user-config.jam</code> file, which 171 should live in your home directory (<code class="computeroutput">/Users/<your_username></code>). 172 You must already have it somewhere or otherwise you could not be building 173 Boost (i.e. missing tools configuration). 174 </p> 175<pre class="programlisting">using xsltproc ; 176 177using boostbook 178 : "/usr/local/share/xsl/docbook" 179 : "/usr/local/share/xml/docbook/4.2" 180 ; 181</pre> 182</li> 183</ol></div> 184<p> 185 The above steps are enough to get a functional BoostBook setup. Quickbook 186 will be automatically built when needed. If you want to avoid these rebuilds 187 and install a system-wide Quickbook instead: 188 </p> 189<div class="orderedlist"><ol class="orderedlist" type="1"> 190<li class="listitem"> 191 Go to Quickbook's source directory (<code class="computeroutput">BOOST_ROOT/tools/quickbook</code>). 192 </li> 193<li class="listitem"> 194 Build the utility by issuing <code class="computeroutput">bjam</code>. 195 </li> 196<li class="listitem"> 197 Copy the resulting <code class="computeroutput">quickbook</code> binary (located at <code class="computeroutput">BOOST_ROOT/dist/bin</code>) 198 to a safe place. Following our previous example, you can install it 199 into: <code class="computeroutput">/usr/local/bin</code>. 200 </li> 201<li class="listitem"> 202<p class="simpara"> 203 Add the following to your <code class="computeroutput">user-config.jam</code> file: 204 </p> 205<pre class="programlisting">using quickbook 206 : "/usr/local/bin/quickbook" ; 207 ; 208</pre> 209</li> 210</ol></div> 211<p> 212 <a name="osx-prebuilt-doxygen"></a>Additionally, if you need to build documentation 213 that uses <a href="http://www.doxygen.org" target="_top">Doxygen</a>, you will 214 need to install it too: 215 </p> 216<div class="orderedlist"><ol class="orderedlist" type="1"> 217<li class="listitem"> 218 Go to the <a href="http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc" target="_top">downloads 219 section</a> and get the disk image (<code class="computeroutput">dmg</code> file) for 220 Mac OS X. 221 </li> 222<li class="listitem"> 223 Open the disk image and drag the Doxygen application to your <code class="computeroutput">Applications</code> 224 folder to install it. 225 </li> 226<li class="listitem"> 227<p class="simpara"> 228 Add the following to your <code class="computeroutput">user-config.jam</code> file: 229 </p> 230<pre class="programlisting">using doxygen 231 : /Applications/Doxygen.app/Contents/Resources/doxygen 232 ; 233</pre> 234</li> 235</ol></div> 236</div> 237</div> 238<div class="section"> 239<div class="titlepage"><div><div><h3 class="title"> 240<a name="quickbook.install.windows"></a><a class="link" href="install.html#quickbook.install.windows" title="Windows 2000, XP, 2003, Vista, 7">Windows 2000, XP, 2003, Vista, 241 7</a> 242</h3></div></div></div> 243<div class="blockquote"><blockquote class="blockquote"><p> 244 <span class="emphasis"><em>Section contributed by Julio M. Merino Vidal</em></span> 245 </p></blockquote></div> 246<p> 247 The following instructions apply to any Windows system based on Windows 2000, 248 including Windows XP, Windows 2003 Server, Windows Vista, and Windows 7. 249 The paths shown below are taken from a Windows Vista machine; you will need 250 to adjust them to match your system in case you are running an older version. 251 </p> 252<div class="orderedlist"><ol class="orderedlist" type="1"> 253<li class="listitem"> 254 First of all you need to have a copy of <code class="computeroutput">xsltproc</code> for Windows. 255 There are many ways to get this tool, but to keep things simple, use 256 the <a href="http://www.zlatkovic.com/pub/libxml/" target="_top">binary packages</a> 257 made by Igor Zlatkovic. At the very least, you need to download the following 258 packages: <code class="computeroutput">iconv</code>, <code class="computeroutput">zlib</code>, <code class="computeroutput">libxml2</code> 259 and <code class="computeroutput">libxslt</code>. 260 </li> 261<li class="listitem"> 262 Unpack all these packages in the same directory so that you get unique 263 <code class="computeroutput">bin</code>, <code class="computeroutput">include</code> and <code class="computeroutput">lib</code> directories 264 within the hierarchy. These instructions use <code class="computeroutput">C:\Users\example\Documents\boost\xml</code> 265 as the root for all files. 266 </li> 267<li class="listitem"> 268 From the command line, go to the <code class="computeroutput">bin</code> directory and launch 269 <code class="computeroutput">xsltproc.exe</code> to ensure it works. You should get usage information 270 on screen. 271 </li> 272<li class="listitem"> 273 Download <a href="http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip" target="_top">Docbook 274 XML 4.2</a> and unpack it in the same directory used above. That 275 is: <code class="computeroutput">C:\Users\example\Documents\boost\xml\docbook-xml</code>. 276 </li> 277<li class="listitem"> 278 Download the latest <a href="http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608" target="_top">Docbook 279 XSL</a> version and unpack it, again in the same directory used before. 280 Be careful that you download the correct file, sometimes the 'looking 281 for the latest version' link often links to another file. The name should 282 be of the form <code class="computeroutput">docbook-xsl-1.<span class="emphasis"><em>nn</em></span>.<span class="emphasis"><em>n</em></span>.tar.bz2</code>, with no suffix such as <code class="computeroutput">-ns.tar.bz2</code> or 283 <code class="computeroutput">-doc.tar.bz2</code>. To make things easier, rename the directory 284 created during the extraction to <code class="computeroutput">docbook-xsl</code> (bypassing 285 the version name): <code class="computeroutput">C:\Users\example\Documents\boost\xml\docbook-xsl</code>. 286 </li> 287<li class="listitem"> 288<p class="simpara"> 289 Add the following to your <code class="computeroutput">user-config.jam</code> file, which should 290 live in your home directory (<code class="computeroutput">%HOMEDRIVE%%HOMEPATH%</code>). You 291 must already have it somewhere or otherwise you could not be building 292 Boost (i.e. missing tools configuration). 293 </p> 294<pre class="programlisting">using xsltproc 295 : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" 296 ; 297 298using boostbook 299 : "C:/Users/example/Documents/boost/xml/docbook-xsl" 300 : "C:/Users/example/Documents/boost/xml/docbook-xml" 301 ; 302</pre> 303</li> 304</ol></div> 305<p> 306 The above steps are enough to get a functional BoostBook setup. Quickbook 307 will be automatically built when needed. If you want to avoid these rebuilds: 308 </p> 309<div class="orderedlist"><ol class="orderedlist" type="1"> 310<li class="listitem"> 311 Go to Quickbook's source directory (<code class="computeroutput">BOOST_ROOT\tools\quickbook</code>). 312 </li> 313<li class="listitem"> 314 Build the utility by issuing <code class="computeroutput">bjam</code>. 315 </li> 316<li class="listitem"> 317 Copy the resulting <code class="computeroutput">quickbook.exe</code> binary (located at <code class="computeroutput">BOOST_ROOT\dist\bin</code>) 318 to a safe place. Following our previous example, you can install it into: 319 <code class="computeroutput">C:\Users\example\Documents\boost\xml\bin</code>. 320 </li> 321<li class="listitem"> 322<p class="simpara"> 323 Add the following to your <code class="computeroutput">user-config.jam</code> file: 324 </p> 325<pre class="programlisting">using quickbook 326 : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" 327 ; 328</pre> 329</li> 330</ol></div> 331</div> 332<div class="section"> 333<div class="titlepage"><div><div><h3 class="title"> 334<a name="quickbook.install.linux"></a><a class="link" href="install.html#quickbook.install.linux" title="Debian, Ubuntu">Debian, Ubuntu</a> 335</h3></div></div></div> 336<p> 337 The following instructions apply to Debian and its derivatives. They are 338 based on a Ubuntu Edgy install but should work on other Debian based systems. 339 They assume you've already installed an appropriate version of <code class="computeroutput">bjam</code> 340 for your copy of boost. 341 </p> 342<p> 343 First install the <code class="computeroutput">xsltproc</code>, <code class="computeroutput">docbook-xsl</code> and <code class="computeroutput">docbook-xml</code> 344 packages. For example, using <code class="computeroutput">apt-get</code>: 345 </p> 346<pre class="programlisting">sudo apt-get install xsltproc docbook-xsl docbook-xml 347</pre> 348<p> 349 If you're planning on building boost's documentation, you'll also need to 350 install the <code class="computeroutput">doxygen</code> package as well. 351 </p> 352<p> 353 Next, we need to configure Boost Build to compile BoostBook files. Add the 354 following to your <code class="computeroutput">user-config.jam</code> file, which should be in your 355 home directory. If you don't have one, create a file containing this text. 356 For more information on setting up <code class="computeroutput">user-config.jam</code>, see the 357 <a href="http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html" target="_top">Boost 358 Build documentation</a>. 359 </p> 360<pre class="programlisting">using xsltproc ; 361 362using boostbook 363 : /usr/share/xml/docbook/stylesheet/nwalsh 364 : /usr/share/xml/docbook/schema/dtd/4.2 365 ; 366 367# Remove this line if you're not using doxygen 368using doxygen ; 369</pre> 370<p> 371 The above steps are enough to get a functional BoostBook setup. Quickbook 372 will be automatically built when needed. If you want to avoid these rebuilds: 373 </p> 374<div class="orderedlist"><ol class="orderedlist" type="1"> 375<li class="listitem"> 376 Go to Quickbook's source directory (<code class="computeroutput">BOOST_ROOT/tools/quickbook</code>). 377 </li> 378<li class="listitem"> 379 Build the utility by issuing <code class="computeroutput">bjam</code>. 380 </li> 381<li class="listitem"> 382 Copy the resulting <code class="computeroutput">quickbook</code> binary (located at <code class="computeroutput">BOOST_ROOT/dist/bin</code>) 383 to a safe place. The traditional location is <code class="computeroutput">/usr/local/bin</code>. 384 </li> 385<li class="listitem"> 386<p class="simpara"> 387 Add the following to your <code class="computeroutput">user-config.jam</code> file, using the 388 full path of the quickbook executable: 389 </p> 390<pre class="programlisting">using quickbook 391 : /usr/local/bin/quickbook 392 ; 393</pre> 394</li> 395</ol></div> 396</div> 397</div> 398<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 399<td align="left"></td> 400<td align="right"><div class="copyright-footer">Copyright © 2002, 2004, 2006 Joel de Guzman, 401 Eric Niebler<br>Copyright © 2010-2017 Daniel James<p> 402 Distributed under the Boost Software License, Version 1.0. (See accompanying 403 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>) 404 </p> 405</div></td> 406</tr></table> 407<hr> 408<div class="spirit-nav"> 409<a accesskey="p" href="versions.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> 410</div> 411</body> 412</html> 413
