diff options
Diffstat (limited to 'more/getting_started/windows.rst')
| -rw-r--r-- | more/getting_started/windows.rst | 340 |
1 files changed, 0 insertions, 340 deletions
diff --git a/more/getting_started/windows.rst b/more/getting_started/windows.rst deleted file mode 100644 index d1f4494643..0000000000 --- a/more/getting_started/windows.rst +++ /dev/null @@ -1,340 +0,0 @@ -.. 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/build/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. - -.. 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 |