doc/html/quickbook/install.html

   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=US-ASCII">
   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&#160;51.&#160;Quickbook 1.6">
  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
  82 using 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&amp;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/&lt;your_username&gt;</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
 177 using 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&amp;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
 298 using 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
 362 using 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
 368 using 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 &#169; 2002, 2004, 2006 Joel de Guzman,
 401       Eric Niebler<br>Copyright &#169; 2010, 2011 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>