]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler | |
3 | Copyright 2010-2011 Daniel James | |
4 | ||
5 | Distributed under the Boost Software License, Version 1.0. | |
6 | (See accompanying file LICENSE_1_0.txt or copy at | |
7 | http://www.boost.org/LICENSE_1_0.txt) | |
8 | ] | |
9 | ||
10 | [chapter Installation and configuration | |
11 | [quickbook 1.6] | |
12 | [compatibility-mode 1.5] | |
13 | [id quickbook.install] | |
14 | [source-mode teletype] | |
15 | ] | |
16 | ||
17 | This section provides some guidelines on how to install and configure | |
18 | BoostBook and Quickbook under several operating systems. Before installing | |
19 | you'll need a local copy of boost, and to install the version of `bjam` | |
20 | which comes with it (or a later version). | |
21 | ||
22 | [/ I don't think this is needed any more] | |
23 | [/ | |
24 | Before continuing, it is very important that you keep this in mind: if you | |
25 | try to build some documents and the process breaks due to misconfiguration, | |
26 | be absolutely sure to delete any `bin` and `bin.v2` directories generated | |
27 | by the build before trying again. Otherwise your configuration fixes will | |
28 | not take any effect. | |
29 | ] | |
30 | ||
31 | [section:macosx Mac OS X] | |
32 | ||
33 | The simplest way to install on OS X is to use macports. | |
34 | If you don't want to use macports and are using Snow Leopard or later, | |
35 | there are instructions [link quickbook.install.macosx.native later]. | |
36 | Earlier versions of OS X need to use something like macports to install | |
37 | `xsltproc` because the version they come with is very old, and doesn't have | |
38 | good enough XSL support for boostbook's stylesheets. | |
39 | ||
40 | [section:macports Mac OS X, using macports] | |
41 | ||
42 | First install the `libxslt`, `docbook-xsl` and `docbook-xml-4.2` | |
43 | packages: | |
44 | ||
45 | sudo port install libxslt docbook-xsl docbook-xml-4.2 | |
46 | ||
47 | Next, we need to configure Boost Build to compile BoostBook files. Add the | |
48 | following to your `user-config.jam` file, which should be in your home | |
49 | directory. If you don't have one, create a file containing this text. For more | |
50 | information on setting up `user-config.jam`, see the | |
51 | [@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost | |
52 | Build documentation]. | |
53 | ||
54 | using xsltproc | |
55 | : /opt/local/bin/xsltproc | |
56 | ; | |
57 | ||
58 | using boostbook | |
59 | : /opt/local/share/xsl/docbook-xsl/ | |
60 | : /opt/local/share/xml/docbook/4.2 | |
61 | ; | |
62 | ||
63 | The above steps are enough to get a functional BoostBook setup. Quickbook | |
64 | will be automatically built when needed. If you want to avoid these | |
65 | rebuilds: | |
66 | ||
67 | # Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`). | |
68 | ||
69 | # Build the utility by issuing `bjam`. | |
70 | ||
71 | # Copy the resulting `quickbook` binary (located at | |
72 | `BOOST_ROOT/dist/bin`) to a safe place. The traditional location is | |
73 | `/usr/local/bin`. | |
74 | ||
75 | # Add the following to your `user-config.jam` file, using the full path of the | |
76 | quickbook executable: | |
77 | ``` | |
78 | using quickbook | |
79 | : /usr/local/bin/quickbook | |
80 | ; | |
81 | ``` | |
82 | ||
83 | If you need to build documentation that uses Doxygen, you will need to install it as well: | |
84 | ||
85 | sudo port install doxygen | |
86 | ||
87 | And then add to your `user-config.jam`: | |
88 | ||
89 | using doxygen ; | |
90 | ||
91 | Alternatively, you can install from the official doxygen `dmg`. | |
92 | This is described at [link osx-prebuilt-doxygen the end of the next section]. | |
93 | ||
94 | [endsect] [/ macports] | |
95 | ||
96 | [section:native Mac OS X, Snow Leopard (or later)] | |
97 | ||
98 | [:['Section contributed by Julio M. Merino Vidal]] | |
99 | ||
100 | The text below assumes you want to install all the necessary utilities in a | |
101 | system-wide location, allowing any user in the machine to have access to | |
102 | them. Therefore, all files will be put in the `/usr/local` hierarchy. If | |
103 | you do not want this, you can choose any other prefix such as | |
104 | `~/Applications` for a single-user installation. | |
105 | ||
106 | Snow Leopard comes with `xsltproc` and all related libraries preinstalled, so | |
107 | you do not need to take any extra steps to set them up. It is probable | |
108 | that future versions will include them too, but these instructions may not | |
109 | apply to older versions. | |
110 | ||
111 | To get started: | |
112 | ||
113 | # Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML | |
114 | 4.2] and unpack it inside `/usr/local/share/xml/docbook/4.2`. | |
115 | ||
116 | # Download the latest | |
117 | [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608 | |
118 | Docbook XSL] version and unpack it. Be careful that you download the correct | |
119 | file, sometimes the 'looking for the latest version' link often links to | |
120 | another file. The name should be of the form | |
121 | '''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''', | |
122 | with no suffix such as `-ns.tar.bz2` or `-doc.tar.bz2`. | |
123 | Put the results in | |
124 | `/usr/local/share/xsl/docbook`, thus effectively removing the version | |
125 | number from the directory name (for simplicity). | |
126 | ||
127 | # Add the following to your `user-config.jam` file, which should live in | |
128 | your home directory (`/Users/<your_username>`). You must already have it | |
129 | somewhere or otherwise you could not be building Boost (i.e. missing | |
130 | tools configuration). | |
131 | ``` | |
132 | using xsltproc ; | |
133 | ||
134 | using boostbook | |
135 | : "/usr/local/share/xsl/docbook" | |
136 | : "/usr/local/share/xml/docbook/4.2" | |
137 | ; | |
138 | ``` | |
139 | ||
140 | The above steps are enough to get a functional BoostBook setup. Quickbook | |
141 | will be automatically built when needed. If you want to avoid these | |
142 | rebuilds and install a system-wide Quickbook instead: | |
143 | ||
144 | # Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`). | |
145 | ||
146 | # Build the utility by issuing `bjam`. | |
147 | ||
148 | # Copy the resulting `quickbook` binary (located at | |
149 | `BOOST_ROOT/dist/bin`) to a safe place. Following our previous | |
150 | example, you can install it into: `/usr/local/bin`. | |
151 | ||
152 | # Add the following to your `user-config.jam` file: | |
153 | ``` | |
154 | using quickbook | |
155 | : "/usr/local/bin/quickbook" ; | |
156 | ; | |
157 | ``` | |
158 | ||
159 | [# osx-prebuilt-doxygen] | |
160 | Additionally, if you need to build documentation that uses | |
161 | [@http://www.doxygen.org Doxygen], you will need to install it too: | |
162 | ||
163 | # Go to the [@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc | |
164 | downloads section] and get the disk image (`dmg` file) for Mac OS X. | |
165 | ||
166 | # Open the disk image and drag the Doxygen application to your | |
167 | `Applications` folder to install it. | |
168 | ||
169 | # Add the following to your `user-config.jam` file: | |
170 | ``` | |
171 | using doxygen | |
172 | : /Applications/Doxygen.app/Contents/Resources/doxygen | |
173 | ; | |
174 | ``` | |
175 | ||
176 | [/ Removed this, since there are macports based instructions earlier. | |
177 | Instructions for pkgsrc welcome] | |
178 | [/ | |
179 | Alternatively, you may want to install all the prerequistes through a | |
180 | package system to avoid manual management of the installations. In that | |
181 | case, check out [@http://www.pkgsrc.org pkgsrc]. | |
182 | ] | |
183 | ||
184 | [endsect] [/ native] | |
185 | ||
186 | [endsect] [/ macosx] | |
187 | ||
188 | [section:windows Windows 2000, XP, 2003, Vista, 7] | |
189 | ||
190 | [:['Section contributed by Julio M. Merino Vidal]] | |
191 | ||
192 | The following instructions apply to any Windows system based on Windows | |
193 | 2000, including Windows XP, Windows 2003 Server, Windows Vista, and Windows 7. The | |
194 | paths shown below are taken from a Windows Vista machine; you will need to | |
195 | adjust them to match your system in case you are running an older version. | |
196 | ||
197 | # First of all you need to have a copy of `xsltproc` for Windows. There | |
198 | are many ways to get this tool, but to keep things simple, use the | |
199 | [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor | |
200 | Zlatkovic. At the very least, you need to download the following | |
201 | packages: `iconv`, `zlib`, `libxml2` and `libxslt`. | |
202 | ||
203 | # Unpack all these packages in the same directory so that you get unique | |
204 | `bin`, `include` and `lib` directories within the hierarchy. These | |
205 | instructions use `C:\Users\example\Documents\boost\xml` as the root for | |
206 | all files. | |
207 | ||
208 | # From the command line, go to the `bin` directory and launch | |
209 | `xsltproc.exe` to ensure it works. You should get usage information on | |
210 | screen. | |
211 | ||
212 | # Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML | |
213 | 4.2] and unpack it in the same directory used above. That is: | |
214 | `C:\Users\example\Documents\boost\xml\docbook-xml`. | |
215 | ||
216 | # Download the latest | |
217 | [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608 | |
218 | Docbook XSL] version and unpack it, again in the same directory | |
219 | used before. Be careful that you download the correct | |
220 | file, sometimes the 'looking for the latest version' link often links to | |
221 | another file. The name should be of the form | |
222 | '''<code>docbook-xsl-1.<emphasis>nn</emphasis>.<emphasis>n</emphasis>.tar.bz2</code>''', | |
223 | with no suffix such as `-ns.tar.bz2` or `-doc.tar.bz2`. | |
224 | To make things easier, rename the directory created | |
225 | during the extraction to `docbook-xsl` (bypassing the version name): | |
226 | `C:\Users\example\Documents\boost\xml\docbook-xsl`. | |
227 | ||
228 | # Add the following to your `user-config.jam` file, which should live in | |
229 | your home directory (`%HOMEDRIVE%%HOMEPATH%`). You must already have it | |
230 | somewhere or otherwise you could not be building Boost (i.e. missing | |
231 | tools configuration). | |
232 | ``` | |
233 | using xsltproc | |
234 | : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" | |
235 | ; | |
236 | ||
237 | using boostbook | |
238 | : "C:/Users/example/Documents/boost/xml/docbook-xsl" | |
239 | : "C:/Users/example/Documents/boost/xml/docbook-xml" | |
240 | ; | |
241 | ``` | |
242 | ||
243 | The above steps are enough to get a functional BoostBook setup. Quickbook | |
244 | will be automatically built when needed. If you want to avoid these | |
245 | rebuilds: | |
246 | ||
247 | # Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`). | |
248 | ||
249 | # Build the utility by issuing `bjam`. | |
250 | ||
251 | # Copy the resulting `quickbook.exe` binary (located at | |
252 | `BOOST_ROOT\dist\bin`) to a safe place. Following our previous | |
253 | example, you can install it into: | |
254 | `C:\Users\example\Documents\boost\xml\bin`. | |
255 | ||
256 | # Add the following to your `user-config.jam` file: | |
257 | ``` | |
258 | using quickbook | |
259 | : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" | |
260 | ; | |
261 | ``` | |
262 | ||
263 | [endsect] [/Windows] | |
264 | ||
265 | [section:linux Debian, Ubuntu] | |
266 | ||
267 | The following instructions apply to Debian and its derivatives. They are based | |
268 | on a Ubuntu Edgy install but should work on other Debian based systems. They | |
269 | assume you've already installed an appropriate version of `bjam` for your | |
270 | copy of boost. | |
271 | ||
272 | First install the `xsltproc`, `docbook-xsl` and `docbook-xml` packages. | |
273 | For example, using `apt-get`: | |
274 | ||
275 | sudo apt-get install xsltproc docbook-xsl docbook-xml | |
276 | ||
277 | If you're planning on building boost's documentation, you'll also need to | |
278 | install the `doxygen` package as well. | |
279 | ||
280 | Next, we need to configure Boost Build to compile BoostBook files. Add the | |
281 | following to your `user-config.jam` file, which should be in your home | |
282 | directory. If you don't have one, create a file containing this text. For more | |
283 | information on setting up `user-config.jam`, see the | |
284 | [@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost | |
285 | Build documentation]. | |
286 | ||
287 | using xsltproc ; | |
288 | ||
289 | using boostbook | |
290 | : /usr/share/xml/docbook/stylesheet/nwalsh | |
291 | : /usr/share/xml/docbook/schema/dtd/4.2 | |
292 | ; | |
293 | ||
294 | # Remove this line if you're not using doxygen | |
295 | using doxygen ; | |
296 | ||
297 | The above steps are enough to get a functional BoostBook setup. Quickbook | |
298 | will be automatically built when needed. If you want to avoid these | |
299 | rebuilds: | |
300 | ||
301 | # Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`). | |
302 | ||
303 | # Build the utility by issuing `bjam`. | |
304 | ||
305 | # Copy the resulting `quickbook` binary (located at | |
306 | `BOOST_ROOT/dist/bin`) to a safe place. The traditional location is | |
307 | `/usr/local/bin`. | |
308 | ||
309 | # Add the following to your `user-config.jam` file, using the full path of the | |
310 | quickbook executable: | |
311 | ``` | |
312 | using quickbook | |
313 | : /usr/local/bin/quickbook | |
314 | ; | |
315 | ``` | |
316 | ||
317 | [endsect] [/Linux] |