diff options
Diffstat (limited to 'more/getting_started/windows.rst')
| -rw-r--r-- | more/getting_started/windows.rst | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/more/getting_started/windows.rst b/more/getting_started/windows.rst new file mode 100644 index 0000000000..29d5b5ea2f --- /dev/null +++ b/more/getting_started/windows.rst @@ -0,0 +1,348 @@ +.. 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 most reliable way to get a copy of Boost is to +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 + +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 + .\b2 + +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 allowed options. + +__ 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|> b2 **^** + 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 Boost.Build 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 + +.. [#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 |