ceph/src/boost/more/getting_started/windows.rst

   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