From 1b90c7d89ba2776773808ef3ac3793e8150a5649 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Wed, 14 Nov 2007 17:37:55 +0000 Subject: [PATCH] Update command-prompt instructions per http://news.gmane.org/find-root.php?message_id=%3cfhcrem%24c4%241%40ger.gmane.org%3e [SVN r41094] --- getting_started/windows.html | 128 ++++++++++++++++++++--------------- getting_started/windows.rst | 35 ++++++++-- 2 files changed, 102 insertions(+), 61 deletions(-) diff --git a/getting_started/windows.html b/getting_started/windows.html index 02bdc2c..38a57eb 100644 --- a/getting_started/windows.html +++ b/getting_started/windows.html @@ -26,40 +26,40 @@ not supported—they may or may not work.

Index

-

1   Get Boost

+

1   Get Boost

The easiest way to get a copy of Boost is to use the installer provided by Boost Consulting. We especially recommend this method if you use Microsoft Visual Studio .NET 2003 or Microsoft @@ -76,7 +76,7 @@ distribution.1

-

2   The Boost Distribution

+

2   The Boost Distribution

This is a sketch of the resulting directory structure:

 boost_1_35_0\ .................The “boost root directory”
@@ -159,7 +159,7 @@ contains a subset of the Boost documentation.  Start with
-

3   Header-Only Libraries

+

3   Header-Only Libraries

The first thing many people want to know is, “how do I build Boost?” The good news is that often, there's nothing to build.

@@ -199,7 +199,7 @@ use.
-

4   Build a Simple Program Using Boost

+

4   Build a Simple Program Using Boost

To keep things simple, let's start by using a header-only library. The following program reads a sequence of integers from standard input, uses Boost.Lambda to multiply each number by three, and @@ -255,7 +255,7 @@ caret (^) at the end on this page use that technique to save horizontal space.

-

4.1   Build From the Visual Studio IDE

+

4.1   Build From the Visual Studio IDE

  • From Visual Studio's File menu, select New > Project…

    • @@ -296,7 +296,7 @@ Return key.

    skip to the next step

-

4.2   Or, Build From the Command Prompt

+

4.2   Or, Build From the Command Prompt

From your computer's Start menu, if you are a Visual Studio 2005 user, select

@@ -322,7 +322,7 @@ echo 1 2 3 | example
-

4.3   Errors and Warnings

+

4.3   Errors and Warnings

Don't be alarmed if you see compiler warnings originating in Boost headers. We try to eliminate them, but doing so isn't always practical.5 Errors are another matter. If you're @@ -335,11 +335,11 @@ correctly identified the -

5   Prepare to Use a Boost Library Binary

+

5   Prepare to Use a Boost Library Binary

If you want to use any of the separately-compiled Boost libraries, you'll need to acquire library binaries.

-

5.1   Install Visual Studio (2005 or .NET 2003) Binaries

+

5.1   Install Visual Studio (2005 or .NET 2003) Binaries

The installer supplied by Boost Consulting will download and install pre-compiled binaries into the lib\ subdirectory of the boost root, typically C:\Program Files\boost\boost_1_35_0\lib\. If you installed @@ -349,7 +349,7 @@ now.

skip to the next step

-

5.2   Or, Build Binaries From Source

+

5.2   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.

@@ -361,7 +361,7 @@ installing software. To use it, you'll need an executable called bjam.

-

5.2.1   Get bjam

+

5.2.1   Get bjam

bjam is the command-line tool that drives the Boost Build system. To build Boost binaries, you'll invoke bjam from the Boost root.

@@ -370,7 +370,7 @@ Alternatively, you can build bjam instructions.

-

5.2.2   Identify Your Toolset

+

5.2.2   Identify Your Toolset

First, find the toolset corresponding to your compiler in the following table.

@@ -475,7 +475,7 @@ are using the msvc or gcc toolsets, which have special version detection code) or auto-linking will fail.

-

5.2.3   Select a Build Directory

+

5.2.3   Select a Build Directory

Boost.Build will place all intermediate files it generates while building into the build directory. If your Boost root directory is writable, this step isn't strictly necessary: by @@ -483,7 +483,7 @@ default Boost.Build will create a

-

5.2.4   Invoke bjam

+

5.2.4   Invoke bjam

Change your current directory to the Boost root directory and invoke bjam as follows:

@@ -493,9 +493,11 @@ bjam --build-dir=
 C:\WINDOWS> cd C:\Program Files\boost\boost_1_35_0
 C:\Program Files\boost\boost_1_35_0> bjam ^
-More? --build-dir=C:\temp\build-boost ^
+More? --build-dir="C:\Documents and Settings\dave\build-boost" ^
 More? --toolset=msvc stage
+

Be sure to read this note about the appearance of ^, +More? and quotation marks (") in that line.

@@ -523,7 +525,7 @@ be interested in:

-

5.3   Expected Build Output

+

5.3   Expected Build Output

During the process of building Boost libraries, you can expect to see some messages printed on the console. These may include

    @@ -547,7 +549,7 @@ look something like:

-

5.4   In Case of Build Errors

+

5.4   In Case of Build Errors

The only error messages you see when building Boost—if any—should be related to the IOStreams library's support of zip and bzip2 formats as described here. Install the relevant development @@ -565,7 +567,7 @@ questions about configuring Boost for your compiler to the

-

6.3   Library Naming

+

6.3   Library Naming

Note

If, like Visual C++, your compiler supports auto-linking, @@ -657,7 +659,7 @@ following elements:

Prefix: except on Microsoft Windows, every Boost library name begins with this string. On Windows, only ordinary static libraries use the lib prefix; import libraries and DLLs do -not.6
+not.6
boost_regex
Library name: all boost library filenames begin with boost_.
-vc71
@@ -695,14 +697,14 @@ libraries. using a special debug build of Python. d -building a debug version of your code.7 +building a debug version of your code.7 p using the STLPort standard library rather than the default one supplied with your compiler. n -using STLPort's deprecated “native iostreams” feature.8 +using STLPort's deprecated “native iostreams” feature.8 @@ -735,7 +737,7 @@ version number, will also be created.
-

6.4   Test Your Program

+

6.4   Test Your Program

To test our subject extraction, we'll filter the following text file. Copy it out of your browser and save it as jayne.txt:

@@ -757,7 +759,7 @@ Spoil Rock Hunter?”
-

7   Conclusion and Further Resources

+

7   Conclusion and Further Resources

This concludes your introduction to Boost and to integrating it with your programs. As you start using Boost in earnest, there are surely a few additional points you'll wish we had covered. One day @@ -813,11 +815,25 @@ used in the examples. - +
[4]In this example, the caret character ^ is a -way of continuing the command on multiple lines. 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.
[4]

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

+
+--build-dir="C:\Documents_and_Settings\dave\build-boost"
+
+

Also, for example, you can't add spaces around the = sign as in

+
+--build-dir_=_"C:\Documents and Settings\dave\build-boost"
+
+
@@ -837,7 +853,7 @@ have any source code mechanism for suppressing warnings. - @@ -846,7 +862,7 @@ same name.
[6]This convention distinguishes the static version of +
[6]This convention distinguishes the static version of a Boost library from the import library for an identically-configured Boost DLL, which would otherwise have the same name.
-
[7]These libraries were compiled without optimization +
[7]These libraries were compiled without optimization or inlining, with full debug symbols enabled, and without NDEBUG #defined. Although it's true that sometimes these choices don't affect binary compatibility with other @@ -856,7 +872,7 @@ compiled code, you can't count on that with Boost libraries.
- diff --git a/getting_started/windows.rst b/getting_started/windows.rst index 1750a00..3fa22fb 100644 --- a/getting_started/windows.rst +++ b/getting_started/windows.rst @@ -10,6 +10,9 @@ :alt: Boost :class: boost-logo +.. role:: raw-html(raw) + :format: html + __ ../../index.htm .. section-numbering:: @@ -201,9 +204,14 @@ For example, your session might look like this: [#continuation]_ C:\\WINDOWS> cd |default-root| |default-root|> bjam **^** - More? **--build-dir=**\ C:\\temp\\build-boost **^** + More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^** More? **--toolset=**\ msvc stage +Be sure to read `this note`__ about the appearance of ``^``, +``More?`` and quotation marks (``"``) in that line. + +__ continuation_ + .. include:: detail/build-from-source-tail.rst .. _auto-linking: @@ -300,10 +308,27 @@ Spoil Rock Hunter?” used in the examples. .. [#continuation] In this example, the caret character ``^`` is a - way of continuing the command on multiple lines. 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. + 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:`"`\ C:\\Documents\ :raw-html:`_`\ and\ :raw-html:`_`\ Settings\\dave\\build-boost\ \ :raw-html:`"` + + Also, for example, you can't add spaces around the ``=`` sign as in + + .. parsed-literal:: + + --build-dir\ :raw-html:`_`\ =\ :raw-html:`_`\ "C:\\Documents and Settings\\dave\\build-boost" .. |boost.zip| replace:: |boost_ver|\ ``.zip``
[8]This feature of STLPort is deprecated because it's +
[8]This feature of STLPort is deprecated because it's impossible to make it work transparently to the user; we don't recommend it.