mirror of
https://github.com/boostorg/more.git
synced 2024-12-26 23:30:29 +08:00
387 lines
13 KiB
ReStructuredText
387 lines
13 KiB
ReStructuredText
.. 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/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
|