]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | .. Copyright David Abrahams 2006. Distributed under the Boost |
2 | .. Software License, Version 1.0. (See accompanying | |
3 | .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
4 | ||
5 | ======================================= | |
6 | |(logo)|__ Getting Started on Windows | |
7 | ======================================= | |
8 | ||
9 | .. |(logo)| image:: ../../boost.png | |
10 | :alt: Boost | |
11 | :class: boost-logo | |
12 | ||
13 | .. role:: raw-html(raw) | |
14 | :format: html | |
15 | ||
16 | __ ../../index.htm | |
17 | ||
18 | .. section-numbering:: | |
19 | ||
20 | .. Admonition:: A note to Cygwin_ and MinGW_ users | |
21 | ||
22 | If you plan to use your tools from the Windows command prompt, | |
23 | you're in the right place. If you plan to build from the Cygwin_ | |
24 | bash shell, you're actually running on a POSIX platform and | |
25 | should follow the instructions for `getting started on Unix | |
26 | variants`_. Other command shells, such as MinGW_\ 's MSYS, are | |
27 | not supported—they may or may not work. | |
28 | ||
29 | .. _`Getting Started on Unix Variants`: unix-variants.html | |
30 | .. _Cygwin: http://www.cygwin.com | |
31 | .. _MinGW: http://mingw.org | |
32 | ||
33 | .. Contents:: Index | |
34 | ||
35 | Get Boost | |
36 | ========= | |
37 | ||
38 | The most reliable way to get a copy of Boost is to | |
39 | download |boost.7z|_ or |boost_zip|_ and unpack it to install a complete Boost | |
40 | distribution. [#zip]_ | |
41 | ||
42 | .. |boost.7z| replace:: |boost_ver|\ ``.7z`` | |
43 | ||
44 | .. _`boost.7z`: `sf-download`_ | |
45 | ||
46 | .. |boost_zip| replace:: |boost_ver|\ ``.zip`` | |
47 | ||
48 | .. _`boost_zip`: `sf-download`_ | |
49 | ||
50 | .. include:: detail/distro.rst | |
51 | ||
52 | .. include:: detail/header-only.rst | |
53 | ||
54 | .. include:: detail/build-simple-head.rst | |
55 | ||
56 | .. _`command prompt`: | |
57 | .. _`command-line tool`: | |
58 | ||
59 | .. Note:: To build the examples in this guide, you can use an | |
60 | Integrated Development Environment (IDE) like Visual Studio, or | |
61 | you can issue commands from the `command prompt`_. Since every | |
62 | IDE and compiler has different options and Microsoft's are by | |
63 | far the dominant compilers on Windows, we only give specific | |
64 | directions here for Visual Studio 2005 and .NET 2003 IDEs and | |
65 | their respective command prompt compilers (using the command | |
66 | prompt is a bit simpler). If you are using another compiler or | |
67 | IDE, it should be relatively easy to adapt these instructions to | |
68 | your environment. | |
69 | ||
70 | .. sidebar:: Command Prompt Basics | |
71 | :class: small | |
72 | ||
73 | In Windows, a command-line tool is invoked by typing its name, | |
74 | optionally followed by arguments, into a *Command Prompt* window | |
75 | and pressing the Return (or Enter) key. | |
76 | ||
77 | To open a generic *Command Prompt*, click the *Start* menu | |
78 | button, click *Run*, type “cmd”, and then click *OK*. | |
79 | ||
80 | .. _current directory: | |
81 | ||
82 | All commands are executed within the context of a **current | |
83 | directory** in the filesystem. To set the current directory, | |
84 | type: | |
85 | ||
86 | .. parsed-literal:: | |
87 | ||
88 | cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* | |
89 | ||
90 | followed by Return. For example, | |
91 | ||
92 | .. parsed-literal:: | |
93 | ||
94 | cd |default-root| | |
95 | ||
96 | Long commands can be continued across several lines by typing a | |
97 | caret (``^``) at the end of all but the last line. Some examples | |
98 | on this page use that technique to save horizontal space. | |
99 | ||
100 | .. _vs-header-only: | |
101 | ||
102 | Build From the Visual Studio IDE | |
103 | -------------------------------- | |
104 | ||
105 | * From Visual Studio's *File* menu, select *New* > *Project…* | |
106 | * In the left-hand pane of the resulting *New Project* dialog, | |
107 | select *Visual C++* > *Win32*. | |
108 | * In the right-hand pane, select *Win32 Console Application* | |
109 | (VS8.0) or *Win32 Console Project* (VS7.1). | |
110 | * In the *name* field, enter “example” | |
111 | * Right-click **example** in the *Solution Explorer* pane and | |
112 | select *Properties* from the resulting pop-up menu | |
113 | * In *Configuration Properties* > *C/C++* > *General* > *Additional Include | |
114 | Directories*, enter the path to the Boost root directory, for example | |
115 | ||
116 | |default-root| | |
117 | ||
118 | * In *Configuration Properties* > *C/C++* > *Precompiled Headers*, change | |
119 | *Use Precompiled Header (/Yu)* to *Not Using Precompiled | |
120 | Headers*. [#pch]_ | |
121 | * Replace the contents of the ``example.cpp`` generated by the IDE | |
122 | with the example code above. | |
123 | * From the *Build* menu, select *Build Solution*. | |
124 | ||
125 | To test your application, hit the F5 key and type the following | |
126 | into the resulting window, followed by the Return key:: | |
127 | ||
128 | 1 2 3 | |
129 | ||
130 | Then hold down the control key and press "Z", followed by the | |
131 | Return key. | |
132 | ||
133 | |next|__ | |
134 | ||
135 | __ `Errors and Warnings`_ | |
136 | ||
137 | Or, Build From the Command Prompt | |
138 | --------------------------------- | |
139 | ||
140 | From your computer's *Start* menu, if you are a Visual | |
141 | Studio 2005 user, select | |
142 | ||
143 | *All Programs* > *Microsoft Visual Studio 2005* | |
144 | > *Visual Studio Tools* > *Visual Studio 2005 Command Prompt* | |
145 | ||
146 | or, if you're a Visual Studio .NET 2003 user, select | |
147 | ||
148 | *All Programs* > *Microsoft Visual Studio .NET 2003* | |
149 | > *Visual Studio .NET Tools* > *Visual Studio .NET 2003 Command Prompt* | |
150 | ||
151 | to bring up a special `command prompt`_ window set up for the | |
152 | Visual Studio compiler. In that window, set the `current | |
153 | directory`_ to a suitable location for creating some temporary | |
154 | files and type the following command followed by the Return key: | |
155 | ||
156 | .. parsed-literal:: | |
157 | ||
158 | cl /EHsc /I |root| *path*\ \\\ *to*\ \\example.cpp | |
159 | ||
160 | To test the result, type: | |
161 | ||
162 | .. parsed-literal:: | |
163 | ||
164 | echo 1 2 3 | example | |
165 | ||
166 | .. include:: detail/errors-and-warnings.rst | |
167 | ||
168 | .. include:: detail/binary-head.rst | |
169 | ||
170 | Simplified Build From Source | |
171 | ---------------------------- | |
172 | ||
173 | If you wish to build from source with Visual C++, you can use a | |
174 | simple build procedure described in this section. Open the command prompt | |
175 | and change your current directory to the Boost root directory. Then, type | |
176 | the following commands:: | |
177 | ||
178 | bootstrap | |
179 | .\b2 | |
180 | ||
181 | The first command prepares the Boost.Build system for use. The second | |
182 | command invokes Boost.Build to build the separately-compiled Boost | |
183 | libraries. Please consult the `Boost.Build documentation`__ for a list | |
184 | of allowed options. | |
185 | ||
186 | __ http://www.boost.org/build/doc/html/bbv2/overview/invocation.html | |
187 | ||
188 | Or, Build Binaries From Source | |
189 | ------------------------------ | |
190 | ||
191 | If you're using an earlier version of Visual C++, or a compiler | |
192 | from another vendor, you'll need to use Boost.Build_ to create your | |
193 | own binaries. | |
194 | ||
195 | .. include:: detail/build-from-source-head.rst | |
196 | ||
197 | For example, your session might look like this: [#continuation]_ | |
198 | ||
199 | .. parsed-literal:: | |
200 | ||
201 | C:\\WINDOWS> cd |default-root| | |
202 | |default-root|> b2 **^** | |
203 | More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^** | |
204 | More? **--build-type=complete** **msvc** stage | |
205 | ||
206 | Be sure to read `this note`__ about the appearance of ``^``, | |
207 | ``More?`` and quotation marks (``"``) in that line. | |
208 | ||
209 | The option “\ **--build-type=complete**\ ” causes Boost.Build to build | |
210 | all supported variants of the libraries. For instructions on how to | |
211 | build only specific variants, please ask on the `Boost.Build mailing | |
212 | list`_. | |
213 | ||
214 | __ continuation_ | |
215 | ||
216 | .. include:: detail/build-from-source-tail.rst | |
217 | ||
218 | .. _auto-linking: | |
219 | ||
220 | .. include:: detail/link-head.rst | |
221 | ||
222 | .. Admonition:: Auto-Linking | |
223 | ||
224 | Most Windows compilers and linkers have so-called “auto-linking | |
225 | support,” which eliminates the second challenge. Special code in | |
226 | Boost header files detects your compiler options and uses that | |
227 | information to encode the name of the correct library into your | |
228 | object files; the linker selects the library with that name from | |
229 | the directories you've told it to search. | |
230 | ||
231 | The GCC toolchains (Cygwin and MinGW) are notable exceptions; | |
232 | GCC users should refer to the `linking instructions for Unix | |
233 | variant OSes`__ for the appropriate command-line options to use. | |
234 | ||
235 | __ unix-variants.html#link-your-program-to-a-boost-library | |
236 | ||
237 | ||
238 | Link From Within the Visual Studio IDE | |
239 | -------------------------------------- | |
240 | ||
241 | Starting with the `header-only example project`__ we created | |
242 | earlier: | |
243 | ||
244 | __ vs-header-only_ | |
245 | ||
246 | 1. Right-click **example** in the *Solution Explorer* pane and | |
247 | select *Properties* from the resulting pop-up menu | |
248 | 2. In *Configuration Properties* > *Linker* > *Additional Library | |
249 | Directories*, enter the path to the Boost binaries, | |
250 | e.g. |default-root|\ ``\lib\``. | |
251 | 3. From the *Build* menu, select *Build Solution*. | |
252 | ||
253 | |next|__ | |
254 | ||
255 | __ `Test Your Program`_ | |
256 | ||
257 | Or, Link From the Command Prompt | |
258 | -------------------------------- | |
259 | ||
260 | For example, we can compile and link the above program from the | |
261 | Visual C++ command-line by simply adding the **bold** text below to | |
262 | the command line we used earlier, assuming your Boost binaries are | |
263 | in |default-root|\ ``\lib``: | |
264 | ||
265 | .. parsed-literal:: | |
266 | ||
267 | cl /EHsc /I |root| example.cpp **^** | |
268 | **/link /LIBPATH:**\ |default-root-bold|\ **\\lib** | |
269 | ||
270 | Library Naming | |
271 | -------------- | |
272 | ||
273 | .. Note:: If, like Visual C++, your compiler supports auto-linking, | |
274 | you can probably |next|__. | |
275 | ||
276 | __ `Test Your Program`_ | |
277 | ||
278 | .. include:: detail/library-naming.rst | |
279 | ||
280 | .. include:: detail/test-head.rst | |
281 | ||
282 | Now, in a `command prompt`_ window, type: | |
283 | ||
284 | .. parsed-literal:: | |
285 | ||
286 | *path*\ \\\ *to*\ \\\ *compiled*\ \\example < *path*\ \\\ *to*\ \\\ jayne.txt | |
287 | ||
288 | The program should respond with the email subject, “Will Success | |
289 | Spoil Rock Hunter?” | |
290 | ||
291 | .. include:: detail/conclusion.rst | |
292 | ||
293 | ------------------------------ | |
294 | ||
295 | .. [#zip] We recommend | |
296 | downloading |boost.7z|_ and using 7-Zip_ to decompress | |
297 | it. We no longer recommend .zip files for Boost because they are twice | |
298 | as large as the equivalent .7z files. We don't recommend using Windows' | |
299 | built-in decompression as it can be painfully slow for large archives. | |
300 | ||
301 | .. _7-Zip: http://www.7-zip.org | |
302 | ||
303 | .. [#pch] There's no problem using Boost with precompiled headers; | |
304 | these instructions merely avoid precompiled headers because it | |
305 | would require Visual Studio-specific changes to the source code | |
306 | used in the examples. | |
307 | ||
308 | .. [#continuation] In this example, the caret character ``^`` is a | |
309 | way of continuing the command on multiple lines, and must be the | |
310 | **final character** used on the line to be continued (i.e. do | |
311 | not follow it with spaces). The command prompt responds with | |
312 | ``More?`` to prompt for more input. Feel free to omit the | |
313 | carets and subsequent newlines; we used them so the example | |
314 | would fit on a page of reasonable width. | |
315 | ||
316 | The command prompt treats each bit of whitespace in the command | |
317 | as an argument separator. That means quotation marks (``"``) | |
318 | are required to keep text together whenever a single | |
319 | command-line argument contains spaces, as in | |
320 | ||
321 | .. parsed-literal:: | |
322 | ||
323 | --build-dir=\ :raw-html:`<strong style="background-color:#B4FFB4">"</strong>`\ C:\\Documents\ :raw-html:`<strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong>`\ and\ :raw-html:`<strong style="color:#B4B4B4; background-color:#B4FFB4">_</strong>`\ Settings\\dave\\build-boost\ \ :raw-html:`<strong style="background-color:#B4FFB4">"</strong>` | |
324 | ||
325 | Also, for example, you can't add spaces around the ``=`` sign as in | |
326 | ||
327 | .. parsed-literal:: | |
328 | ||
329 | --build-dir\ :raw-html:`<strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong>`\ =\ :raw-html:`<strong style="color:#B4B4B4; background-color:#FFB4B4">_</strong>`\ "C:\\Documents and Settings\\dave\\build-boost" | |
330 | ||
331 | .. |boost.zip| replace:: |boost_ver|\ ``.zip`` | |
332 | ||
333 | .. _`boost.zip`: `sf-download`_ | |
334 | ||
335 | .. |build-type-complete| replace:: **--build-type=complete** | |
336 | ||
337 | .. include:: detail/common-footnotes.rst | |
338 | .. include:: detail/release-variables.rst | |
339 | .. include:: detail/common-windows.rst | |
340 | .. include:: detail/links.rst |