From 62c3563838527198d11ad2991f4b75643aa7c0b9 Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Sat, 1 Nov 2008 19:17:28 +0000
Subject: [PATCH] Updates for 1.37 based on commentary by Paul Bristow and
experiences with students at MathWorks.
Also cleaned up the use of --build-type=complete, which was
mis-formatted, and is usually inappropriate on *nix anyway.
[SVN r49524]
---
.../detail/build-from-source-head.rst | 9 +++--
getting_started/detail/common-unix.rst | 3 ++
getting_started/detail/common-windows.rst | 4 +++
getting_started/index.html | 2 +-
getting_started/unix-variants.html | 15 ++++----
getting_started/unix-variants.rst | 9 ++---
getting_started/windows.html | 23 ++++++------
getting_started/windows.rst | 36 +++++++++----------
8 files changed, 52 insertions(+), 49 deletions(-)
diff --git a/getting_started/detail/build-from-source-head.rst b/getting_started/detail/build-from-source-head.rst
index 276f6f5..f031648 100644
--- a/getting_started/detail/build-from-source-head.rst
+++ b/getting_started/detail/build-from-source-head.rst
@@ -6,7 +6,7 @@ Boost.Build_ is a text-based system for developing, testing, and
installing software. To use it, you'll need an executable called
``bjam``.
-.. |precompiled-bjam| replace:: pre-compiled ``bjam`` executables
+.. |precompiled-bjam| replace:: download a pre-built ``bjam`` executable
.. _precompiled-bjam: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941
@@ -22,12 +22,15 @@ Get ``bjam``
system. To build Boost binaries, you'll invoke ``bjam`` from the
Boost root.
-Boost provides |precompiled-bjam|_ for a variety of platforms.
+We suggest you |precompiled-bjam|_ for your platform.
Alternatively, you can build ``bjam`` yourself using `these
instructions`__.
__ `building bjam`_
+Move the ``bjam`` executable into a directory in your PATH. You can
+see the list of directories in your PATH, separated by |pathsep|\ s,
+by typing “\ |path|\ ” at the command prompt.
.. _toolset:
.. _toolset-name:
@@ -123,4 +126,4 @@ invoke ``bjam`` as follows:
.. parsed-literal::
- bjam **--build-dir=**\ |build-directory|_ **--toolset=**\ |toolset-name|_ *[*\ **--build-type=complete**\ *]* stage
+ bjam **--build-dir=**\ |build-directory|_ **--toolset=**\ |toolset-name|_ |build-type-complete| stage
diff --git a/getting_started/detail/common-unix.rst b/getting_started/detail/common-unix.rst
index c1cdf49..09ad5d8 100644
--- a/getting_started/detail/common-unix.rst
+++ b/getting_started/detail/common-unix.rst
@@ -20,5 +20,8 @@
.. |command-line tool| replace:: command-line tool
+.. |pathsep| replace:: colon
+
+.. |path| replace:: ``echo $PATH``
.. include:: common.rst
diff --git a/getting_started/detail/common-windows.rst b/getting_started/detail/common-windows.rst
index fa0102c..75ba004 100644
--- a/getting_started/detail/common-windows.rst
+++ b/getting_started/detail/common-windows.rst
@@ -31,4 +31,8 @@
.. |command-line tool| replace:: `command-line tool`_
+.. |pathsep| replace:: semicolon
+
+.. |path| replace:: ``PATH``
+
.. include:: common.rst
diff --git a/getting_started/index.html b/getting_started/index.html
index c8b8021..86a98dd 100644
--- a/getting_started/index.html
+++ b/getting_started/index.html
@@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Boost Getting Started</title>
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
diff --git a/getting_started/unix-variants.html b/getting_started/unix-variants.html
index f536074..32a10ec 100644
--- a/getting_started/unix-variants.html
+++ b/getting_started/unix-variants.html
@@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Boost Getting Started on Unix Variants</title>
<meta content="Getting Started with Boost on Unix Variants (including Linux and MacOS)" name="description" />
<link rel="stylesheet" href="../../rst.css" type="text/css" />
@@ -302,9 +302,12 @@ installing software. To use it, you'll need an executable called
<p><tt class="docutils literal"><span class="pre">bjam</span></tt> is the command-line tool that drives the Boost Build
system. To build Boost binaries, you'll invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from the
Boost root.</p>
-<p>Boost provides <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941">pre-compiled <tt class="docutils literal"><span class="pre">bjam</span></tt> executables</a> for a variety of platforms.
+<p>We suggest you <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941">download a pre-built <tt class="docutils literal"><span class="pre">bjam</span></tt> executable</a> for your platform.
Alternatively, you can build <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself using <a class="reference external" href="../../doc/html/jam/building.html">these
instructions</a>.</p>
+<p>Move the <tt class="docutils literal"><span class="pre">bjam</span></tt> executable into a directory in your PATH. You can
+see the list of directories in your PATH, separated by colons,
+by typing “<tt class="docutils literal"><span class="pre">echo</span> <span class="pre">$PATH</span></tt>” at the command prompt.</p>
</div>
<div class="section" id="identify-your-toolset">
<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id27">5.2.2 Identify Your Toolset</a></h3>
@@ -421,18 +424,14 @@ purpose in your current working directory.</p>
<p>Change your current directory to the Boost root directory and
invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> as follows:</p>
<pre class="literal-block">
-bjam <strong>--build-dir=</strong><a class="reference internal" href="#id10"><em>build-directory</em></a> <strong>--toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <em>[</em><strong>--build-type=complete</strong><em>]</em> stage
+bjam <strong>--build-dir=</strong><a class="reference internal" href="#id10"><em>build-directory</em></a> <strong>--toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <tt class="docutils literal"> </tt> stage
</pre>
<p>For example, your session might look like this:</p>
<pre class="literal-block">
$ cd ~/<tt class="docutils literal"><span class="pre">boost_1_37_0</span></tt>
$ bjam <strong>--build-dir=</strong>/tmp/build-boost <strong>--toolset=</strong>gcc stage
</pre>
-<p>That will build static and shared non-debug multi-threaded variations of the libraries. To build all variations:</p>
-<pre class="literal-block">
-$ cd ~/<tt class="docutils literal"><span class="pre">boost_1_37_0</span></tt>
-$ bjam <strong>--build-dir=</strong>/tmp/build-boost <strong>--toolset=</strong>gcc <strong>--build-type=complete</strong> stage
-</pre>
+<p>That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”.</p>
<!-- 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) -->
diff --git a/getting_started/unix-variants.rst b/getting_started/unix-variants.rst
index f87eacb..548343e 100644
--- a/getting_started/unix-variants.rst
+++ b/getting_started/unix-variants.rst
@@ -142,12 +142,7 @@ For example, your session might look like this:
$ cd ~/|boost_ver|
$ bjam **--build-dir=**\ /tmp/build-boost **--toolset=**\ gcc stage
-That will build static and shared non-debug multi-threaded variations of the libraries. To build all variations:
-
-.. parsed-literal::
-
- $ cd ~/|boost_ver|
- $ bjam **--build-dir=**\ /tmp/build-boost **--toolset=**\ gcc **--build-type=complete** stage
+That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “``--build-type=complete``”.
.. include:: detail/build-from-source-tail.rst
@@ -237,6 +232,8 @@ Spoil Rock Hunter?”
.. [#lowercase-l] That option is a dash followed by a lowercase “L”
character, which looks very much like a numeral 1 in some fonts.
+.. |build-type-complete| replace:: `` ``
+
.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst
.. include:: detail/common-unix.rst
diff --git a/getting_started/windows.html b/getting_started/windows.html
index 6274efb..a4dea4e 100644
--- a/getting_started/windows.html
+++ b/getting_started/windows.html
@@ -3,7 +3,7 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Boost Getting Started on Windows</title>
<link rel="stylesheet" href="../../rst.css" type="text/css" />
</head>
@@ -366,9 +366,12 @@ installing software. To use it, you'll need an executable called
<p><tt class="docutils literal"><span class="pre">bjam</span></tt> is the <a class="reference internal" href="#command-line-tool">command-line tool</a> that drives the Boost Build
system. To build Boost binaries, you'll invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> from the
Boost root.</p>
-<p>Boost provides <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941">pre-compiled <tt class="docutils literal"><span class="pre">bjam</span></tt> executables</a> for a variety of platforms.
+<p>We suggest you <a class="reference external" href="http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=72941">download a pre-built <tt class="docutils literal"><span class="pre">bjam</span></tt> executable</a> for your platform.
Alternatively, you can build <tt class="docutils literal"><span class="pre">bjam</span></tt> yourself using <a class="reference external" href="../../doc/html/jam/building.html">these
instructions</a>.</p>
+<p>Move the <tt class="docutils literal"><span class="pre">bjam</span></tt> executable into a directory in your PATH. You can
+see the list of directories in your PATH, separated by semicolons,
+by typing “<tt class="docutils literal"><span class="pre">PATH</span></tt>” at the command prompt.</p>
</div>
<div class="section" id="identify-your-toolset">
<span id="toolset-name"></span><span id="toolset"></span><h3><a class="toc-backref" href="#id37">5.2.2 Identify Your Toolset</a></h3>
@@ -488,25 +491,21 @@ purpose in your current working directory.</p>
<p>Change your current directory to the Boost root directory and
invoke <tt class="docutils literal"><span class="pre">bjam</span></tt> as follows:</p>
<pre class="literal-block">
-bjam <strong>--build-dir=</strong><a class="reference internal" href="#id12"><em>build-directory</em></a> <strong>--toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <em>[</em><strong>--build-type=complete</strong><em>]</em> stage
+bjam <strong>--build-dir=</strong><a class="reference internal" href="#id12"><em>build-directory</em></a> <strong>--toolset=</strong><a class="reference internal" href="#toolset-name"><em>toolset-name</em></a> <strong>--build-type=complete</strong> stage
</pre>
<p>For example, your session might look like this:<a class="footnote-reference" href="#continuation" id="id13"><sup>4</sup></a></p>
<pre class="literal-block">
C:\WINDOWS> cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_37_0</span></tt>
<tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_37_0</span></tt>> bjam <strong>^</strong>
More? <strong>--build-dir=</strong>"C:\Documents and Settings\dave\build-boost" <strong>^</strong>
-More? <strong>--toolset=</strong>msvc stage
+More? <strong>--toolset=</strong> <strong>--build-type=complete</strong> msvc stage
</pre>
<p>Be sure to read <a class="reference internal" href="#continuation">this note</a> about the appearance of <tt class="docutils literal"><span class="pre">^</span></tt>,
<tt class="docutils literal"><span class="pre">More?</span></tt> and quotation marks (<tt class="docutils literal"><span class="pre">"</span></tt>) in that line.</p>
-<p>The above example session will build static and shared non-debug multi-threaded
-variations of the libraries. To build all variations:</p>
-<pre class="literal-block">
-C:\WINDOWS> cd <tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_37_0</span></tt>
-<tt class="docutils literal"><span class="pre">C:\Program</span> <span class="pre">Files\boost\</span></tt><tt class="docutils literal"><span class="pre">boost_1_37_0</span></tt>> bjam <strong>^</strong>
-More? <strong>--build-dir=</strong>"C:\Documents and Settings\dave\build-boost" <strong>^</strong>
-More? <strong>--toolset=</strong>msvc <strong>--build-type=complete</strong> stage
-</pre>
+<p>The option “<strong>--build-type=complete</strong>” causes <tt class="docutils literal"><span class="pre">bjam</span></tt> to build
+all supported variants of the libraries. For instructions on how to
+build only specific variants, please ask on the <a class="reference external" href="http://www.boost.org/more/mailing_lists.htm#jamboost">Boost.Build mailing
+list</a>.</p>
<!-- 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) -->
diff --git a/getting_started/windows.rst b/getting_started/windows.rst
index dab2cb2..6026dd7 100644
--- a/getting_started/windows.rst
+++ b/getting_started/windows.rst
@@ -35,14 +35,16 @@ __ ../../index.htm
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 Boost.Regex_ binaries when given the option.
+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
@@ -186,7 +188,7 @@ To test the result, type:
Install Visual Studio Binaries
------------------------------
-The installers will download and
+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
@@ -213,20 +215,15 @@ For example, your session might look like this: [#continuation]_
C:\\WINDOWS> cd |default-root|
|default-root|> bjam **^**
More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^**
- More? **--toolset=**\ msvc stage
+ More? **--toolset=**\ **--build-type=complete** msvc stage
Be sure to read `this note`__ about the appearance of ``^``,
``More?`` and quotation marks (``"``) in that line.
-The above example session will build static and shared non-debug multi-threaded
-variations of the libraries. To build all variations:
-
-.. parsed-literal::
-
- C:\\WINDOWS> cd |default-root|
- |default-root|> bjam **^**
- More? **--build-dir=**\ "C:\\Documents and Settings\\dave\\build-boost" **^**
- More? **--toolset=**\ msvc **--build-type=complete** stage
+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_
@@ -355,6 +352,7 @@ Spoil Rock Hunter?”
.. _`boost.zip`: `sf-download`_
+.. |build-type-complete| replace:: **--build-type=complete**
.. include:: detail/common-footnotes.rst
.. include:: detail/release-variables.rst