doc/html/quickbook/install.html

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