| .. Copyright David Abrahams 2006. Distributed under the Boost |
| .. Software License, Version 1.0. (See accompanying |
| .. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) |
| |
| ======================================= |
| |(logo)|__ Getting Started on Windows |
| ======================================= |
| |
| .. |(logo)| image:: ../../boost.png |
| :alt: Boost |
| :class: boost-logo |
| |
| .. role:: raw-html(raw) |
| :format: html |
| |
| __ ../../index.htm |
| |
| .. section-numbering:: |
| |
| .. Admonition:: A note to Cygwin_ and MinGW_ users |
| |
| If you plan to use your tools from the Windows command prompt, |
| you're in the right place. If you plan to build from the Cygwin_ |
| bash shell, you're actually running on a POSIX platform and |
| should follow the instructions for `getting started on Unix |
| variants`_. Other command shells, such as MinGW_\ 's MSYS, are |
| not supported—they may or may not work. |
| |
| .. _`Getting Started on Unix Variants`: unix-variants.html |
| .. _Cygwin: http://www.cygwin.com |
| .. _MinGW: http://mingw.org |
| |
| .. Contents:: Index |
| |
| Get Boost |
| ========= |
| |
| The easiest way to get a copy of Boost is to use an installer. The |
| `Boost website version of this Getting Started guide`_ will have |
| undated information on installers as they become available, or see |
| `Boost downloads`_ or the installer_ provided by `BoostPro |
| Computing`_. We especially recommend using an installer if you use |
| Microsoft Visual Studio, because the installer can download and |
| install precompiled library binaries, saving you the trouble of |
| building them yourself. To complete this tutorial, you'll need to at |
| least install the Static Multithreaded variants of the Boost.Regex_ |
| binaries when given the option. |
| |
| .. _`Boost website version of this Getting Started guide`: |
| http://www.boost.org/doc/libs/1_36_0/more/getting_started/index.html |
| .. _`Boost downloads`: `sf-download`_ |
| .. _installer: http://www.boostpro.com/products/free |
| .. _BoostPro Computing: http://www.boostpro.com |
| |
| If you're using an earlier version of Visual Studio or some other |
| compiler, or if you prefer to build everything yourself, you can |
| download |boost.7z|_ or |boost_zip|_ and unpack it to install a complete Boost |
| distribution. [#zip]_ |
| |
| .. |boost.7z| replace:: |boost_ver|\ ``.7z`` |
| |
| .. _`boost.7z`: `sf-download`_ |
| |
| .. |boost_zip| replace:: |boost_ver|\ ``.zip`` |
| |
| .. _`boost_zip`: `sf-download`_ |
| |
| .. include:: detail/distro.rst |
| |
| .. include:: detail/header-only.rst |
| |
| .. include:: detail/build-simple-head.rst |
| |
| .. _`command prompt`: |
| .. _`command-line tool`: |
| |
| .. Note:: To build the examples in this guide, you can use an |
| Integrated Development Environment (IDE) like Visual Studio, or |
| you can issue commands from the `command prompt`_. Since every |
| IDE and compiler has different options and Microsoft's are by |
| far the dominant compilers on Windows, we only give specific |
| directions here for Visual Studio 2005 and .NET 2003 IDEs and |
| their respective command prompt compilers (using the command |
| prompt is a bit simpler). If you are using another compiler or |
| IDE, it should be relatively easy to adapt these instructions to |
| your environment. |
| |
| .. sidebar:: Command Prompt Basics |
| :class: small |
| |
| In Windows, a command-line tool is invoked by typing its name, |
| optionally followed by arguments, into a *Command Prompt* window |
| and pressing the Return (or Enter) key. |
| |
| To open a generic *Command Prompt*, click the *Start* menu |
| button, click *Run*, type “cmd”, and then click *OK*. |
| |
| .. _current directory: |
| |
| All commands are executed within the context of a **current |
| directory** in the filesystem. To set the current directory, |
| type: |
| |
| .. parsed-literal:: |
| |
| cd *path*\ \\\ *to*\ \\\ *some*\ \\\ *directory* |
| |
| followed by Return. For example, |
| |
| .. parsed-literal:: |
| |
| cd |default-root| |
| |
| Long commands can be continued across several lines by typing a |
| caret (``^``) at the end of all but the last line. Some examples |
| on this page use that technique to save horizontal space. |
| |
| .. _vs-header-only: |
| |
| Build From the Visual Studio IDE |
| -------------------------------- |
| |
| * From Visual Studio's *File* menu, select *New* > *Project…* |
| * In the left-hand pane of the resulting *New Project* dialog, |
| select *Visual C++* > *Win32*. |
| * In the right-hand pane, select *Win32 Console Application* |
| (VS8.0) or *Win32 Console Project* (VS7.1). |
| * In the *name* field, enter “example” |
| * Right-click **example** in the *Solution Explorer* pane and |
| select *Properties* from the resulting pop-up menu |
| * In *Configuration Properties* > *C/C++* > *General* > *Additional Include |
| Directories*, enter the path to the Boost root directory, for example |
| |
| |default-root| |
| |
| * In *Configuration Properties* > *C/C++* > *Precompiled Headers*, change |
| *Use Precompiled Header (/Yu)* to *Not Using Precompiled |
| Headers*. [#pch]_ |
| * Replace the contents of the ``example.cpp`` generated by the IDE |
| with the example code above. |
| * From the *Build* menu, select *Build Solution*. |
| |
| To test your application, hit the F5 key and type the following |
| into the resulting window, followed by the Return key:: |
| |
| 1 2 3 |
| |
| Then hold down the control key and press "Z", followed by the |
| Return key. |
| |
| |next|__ |
| |
| __ `Errors and Warnings`_ |
| |
| Or, Build From the Command Prompt |
| --------------------------------- |
| |
| From your computer's *Start* menu, if you are a Visual |
| Studio 2005 user, select |
| |
| *All Programs* > *Microsoft Visual Studio 2005* |
| > *Visual Studio Tools* > *Visual Studio 2005 Command Prompt* |
| |
| or, if you're a Visual Studio .NET 2003 user, select |
| |
| *All Programs* > *Microsoft Visual Studio .NET 2003* |
| > *Visual Studio .NET Tools* > *Visual Studio .NET 2003 Command Prompt* |
| |
| to bring up a special `command prompt`_ window set up for the |
| Visual Studio compiler. In that window, set the `current |
| directory`_ to a suitable location for creating some temporary |
| files and type the following command followed by the Return key: |
| |
| .. parsed-literal:: |
| |
| cl /EHsc /I |root| *path*\ \\\ *to*\ \\example.cpp |
| |
| To test the result, type: |
| |
| .. parsed-literal:: |
| |
| echo 1 2 3 | example |
| |
| .. include:: detail/errors-and-warnings.rst |
| |
| .. include:: detail/binary-head.rst |
| |
| Install Visual Studio Binaries |
| ------------------------------ |
| |
| The installers supplied by BoostPro Computing will download and |
| install pre-compiled binaries into the ``lib\`` subdirectory of the |
| boost root, typically |default-root|\ ``\lib\``. If you installed |
| all variants of the Boost.Regex_ binary, you're done with this |
| step. Otherwise, please run the installer again and install them |
| now. |
| |
| |next|__ |
| |
| __ `Link Your Program to a Boost Library`_ |
| |
| Or, Simplified Build From Source |
| -------------------------------- |
| |
| If you wish to build from source with Visual C++, you can use a |
| simple build procedure described in this section. Open the command prompt |
| and change your current directory to the Boost root directory. Then, type |
| the following commands:: |
| |
| bootstrap |
| .\bjam |
| |
| The first command prepares the Boost.Build system for use. The second |
| command invokes Boost.Build to build the separately-compiled Boost |
| libraries. Please consult the `Boost.Build documentation`__ for a list |
| of options that can be passed to ``bjam``. |
| |
| __ http://www.boost.org/boost-build2/doc/html/bbv2/overview/invocation.html |
| |
| Or, Build Binaries From Source |
| ------------------------------ |
| |
| If you're using an earlier version of Visual C++, or a compiler |
| from another vendor, you'll need to use Boost.Build_ to create your |
| own binaries. |
| |
| .. Admonition:: Boost.CMake |
| |
| There is also an experimental CMake build for boost, supported and distributed |
| separately. See the `Boost.CMake`_ wiki page for more information. |
| |
| .. _`Boost.CMake`: |
| https://svn.boost.org/trac/boost/wiki/CMake |
| |
| .. include:: detail/build-from-source-head.rst |
| |
| For example, your session might look like this: [#continuation]_ |
| |
| .. parsed-literal:: |
| |
| C:\\WINDOWS> cd |default-root| |
| |default-root|> bjam **^** |
| More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^** |
| More? **--build-type=complete** **msvc** stage |
| |
| Be sure to read `this note`__ about the appearance of ``^``, |
| ``More?`` and quotation marks (``"``) in that line. |
| |
| The option “\ **--build-type=complete**\ ” causes ``bjam`` to build |
| all supported variants of the libraries. For instructions on how to |
| build only specific variants, please ask on the `Boost.Build mailing |
| list`_. |
| |
| __ continuation_ |
| |
| .. include:: detail/build-from-source-tail.rst |
| |
| .. _auto-linking: |
| |
| .. include:: detail/link-head.rst |
| |
| .. Admonition:: Auto-Linking |
| |
| Most Windows compilers and linkers have so-called “auto-linking |
| support,” which eliminates the second challenge. Special code in |
| Boost header files detects your compiler options and uses that |
| information to encode the name of the correct library into your |
| object files; the linker selects the library with that name from |
| the directories you've told it to search. |
| |
| The GCC toolchains (Cygwin and MinGW) are notable exceptions; |
| GCC users should refer to the `linking instructions for Unix |
| variant OSes`__ for the appropriate command-line options to use. |
| |
| __ unix-variants.html#link-your-program-to-a-boost-library |
| |
| |
| Link From Within the Visual Studio IDE |
| -------------------------------------- |
| |
| Starting with the `header-only example project`__ we created |
| earlier: |
| |
| __ vs-header-only_ |
| |
| 1. Right-click **example** in the *Solution Explorer* pane and |
| select *Properties* from the resulting pop-up menu |
| 2. In *Configuration Properties* > *Linker* > *Additional Library |
| Directories*, enter the path to the Boost binaries, |
| e.g. |default-root|\ ``\lib\``. |
| 3. From the *Build* menu, select *Build Solution*. |
| |
| |next|__ |
| |
| __ `Test Your Program`_ |
| |
| Or, Link From the Command Prompt |
| -------------------------------- |
| |
| For example, we can compile and link the above program from the |
| Visual C++ command-line by simply adding the **bold** text below to |
| the command line we used earlier, assuming your Boost binaries are |
| in |default-root|\ ``\lib``: |
| |
| .. parsed-literal:: |
| |
| cl /EHsc /I |root| example.cpp **^** |
| **/link /LIBPATH:**\ |default-root-bold|\ **\\lib** |
| |
| Library Naming |
| -------------- |
| |
| .. Note:: If, like Visual C++, your compiler supports auto-linking, |
| you can probably |next|__. |
| |
| __ `Test Your Program`_ |
| |
| .. include:: detail/library-naming.rst |
| |
| .. include:: detail/test-head.rst |
| |
| Now, in a `command prompt`_ window, type: |
| |
| .. parsed-literal:: |
| |
| *path*\ \\\ *to*\ \\\ *compiled*\ \\example < *path*\ \\\ *to*\ \\\ jayne.txt |
| |
| The program should respond with the email subject, “Will Success |
| Spoil Rock Hunter?” |
| |
| .. include:: detail/conclusion.rst |
| |
| ------------------------------ |
| |
| .. [#zip] We recommend |
| downloading |boost.7z|_ and using 7-Zip_ to decompress |
| it. We no longer recommend .zip files for Boost because they are twice |
| as large as the equivalent .7z files. We don't recommend using Windows' |
| built-in decompression as it can be painfully slow for large archives. |
| |
| .. _7-Zip: http://www.7-zip.org |
| |
| .. [#installer-src] If you used the installer_ from Boost |
| Consulting and deselected “Source and Documentation” (it's |
| selected by default), you won't see the ``libs/`` subdirectory. |
| That won't affect your ability to use precompiled binaries, but |
| you won't be able to rebuild libraries from scratch. |
| |
| .. [#pch] There's no problem using Boost with precompiled headers; |
| these instructions merely avoid precompiled headers because it |
| would require Visual Studio-specific changes to the source code |
| used in the examples. |
| |
| .. [#continuation] In this example, the caret character ``^`` is a |
| way of continuing the command on multiple lines, and must be the |
| **final character** used on the line to be continued (i.e. do |
| not follow it with spaces). The command prompt responds with |
| ``More?`` to prompt for more input. Feel free to omit the |
| carets and subsequent newlines; we used them so the example |
| would fit on a page of reasonable width. |
| |
| The command prompt treats each bit of whitespace in the command |
| as an argument separator. That means quotation marks (``"``) |
| are required to keep text together whenever a single |
| command-line argument contains spaces, as in |
| |
| .. parsed-literal:: |
| |
| --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>` |
| |
| Also, for example, you can't add spaces around the ``=`` sign as in |
| |
| .. parsed-literal:: |
| |
| --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" |
| |
| .. |boost.zip| replace:: |boost_ver|\ ``.zip`` |
| |
| .. _`boost.zip`: `sf-download`_ |
| |
| .. |build-type-complete| replace:: **--build-type=complete** |
| |
| .. include:: detail/common-footnotes.rst |
| .. include:: detail/release-variables.rst |
| .. include:: detail/common-windows.rst |
| .. include:: detail/links.rst |