Boost logo

Boost :

From: David Abrahams (dave_at_[hidden])
Date: 2005-06-18 22:27:33


"Hendrik Schober" <boost_at_[hidden]> writes:

> As I still don't understand Boost.Build (I consider it very
> important to remain as ignorant as the targeted audience
> while working on this guide. :o> ), I'd like this to first
> be reviewed here instead of just checking it in.

Your reference to building bjam is

  ../tools/build/jam_src/index.html

but it should be

  ../tools/build/jam_src/index.html#building_bjam

And first you need to tell people that before following those
instructions they need to be in the tools/build/jam_src subdirectory
of their Boost installation.

---
Okay, I remember rewriting this sentence for you:
  Most of Boost's libraries are header-only. 
I suggested:
  Most Boost libraries consist entirely of header files.  
---
The section entitled 
    Add the Boost root directory to the compiler's #include <...> path
should probably not start with the sentence
    Add the Boost root directory to the compiler's #include <...> path
It's just a wee bit redundant :)
---
I'm pretty sure I suggested this bit:
  If are used doing everything through an IDE, don't worry. The rest
  of these instructions will walk you through all the steps necessary.
But I'm also pretty sure I wrote something more like "If _you_ are used
_to_ doing..."  What was my original wording?  I think this part should
go in a callout box.
---
I'm pretty sure I made this point before: we should not mention
building with multiple toolsets ("You can build the libraries for one
or more toolsets"), especially without supplying any instructions on
how to do it.  The new user can just invoke bjam multiple times.  If I
didn't mention it, I thought it :)
---
    See here how you can tailor Boost.Build for your platform.
and
    See here how to do this.
are ungrammatical.
Furthermore, the 1st "here" link doesn't point at information on
tailoring Boost.Build for a particular platform.  You should drop that
sentence.  Am I imagining things, or did I already make that point?
And the 2nd "here" doesn't point at the information it claims either.
Am I imagining things, or did I already make that point?  To find out
about variable settings, you need to click the name of the toolset in
the table above.
    More information on how to use bjam can be found here.
I honestly think it's a bad idea to point people to that document at
this point in the getting started guide.  It's just a distraction, and
there's even some misleading information at the beginning of it.
---
  To prepare Unix tools such as GCC, the compiler and linker must be
  in your PATH. (Depending on your installation, a Unix compiler such
  as GCC may have additional requirements.) Many Unix operating
  systems come preconfigured and require no user intervention.
  (If you don't want to clutter your environment with settings or you
  have a nonstandard installations for some of the tools, you need to
  set variables which point to the toolset installation directories,
  either in the command shell environment or on the bjam
  command-line. See here how to do this.
  More information on how to use bjam can be found here.)
Note: In US english, "which" can only be used in a phrase that could
be removed from a sentence without changing its meaning, which means
it's usually after a comma.  Use "that" otherwise.
Parenthesization: lay off the parens!  If it's not important, leave it
out, or at least push it down into a footnote.  Also, having a paragraph
break inside of parentheses is really too much!  This should have
been:
    
  To prepare Unix tools such as GCC, the compiler and linker must be
  in your PATH. [1] Many Unix operating systems come preconfigured and
  require no user intervention.
  If you don't want to clutter your environment with settings or if
  your toolset has a nonstandard installation, you may need to pass
  some configuration variables to bjam.  Click the name of a toolset
  in the table above to learn more.
---
You can still break up getting_started-build.html into more pages:
* Select Libraries
* Get the Build Tool
* Select a Toolset
* Select an Installation Directory
* Build and Install
  (this includes "Configuring the Build")
---
  (If you don't build the Boost libraries, because you exclusively use
  the header-only libraries, the folder containing the downloaded
  Boost distribution will be your root directory.)
Lay off the parens.  You could just drop them.  This sentence is
important after all!  Also drop the first comma.
---
  Boost root directory
Okay, the information here is wrong; I must've led you astray because
I've never done this installation thing before.  Traditionally, at
least, the Boost root directory (sometimes referred to as $BOOST_ROOT)
is the parent of the directory called "boost/" that contains header
files like "shared_ptr.hpp".  In this case, it would be the directory
called boost_1_32_0.  So we should take the term "Boost root" out of
this getting_started discussion entirely; it will just confound
people.  Instead, we can use the term "#include root."
We don't want to tell people that they can  let bjam use the
defaults and move the directory structure later because on Unix, at
least, there will probably be other things in /usr/local/include and
/usr/local/lib that shouldn't be moved.
I'm going to rewrite that whole section here, removing awkward/empty
wording.  Unindent to get reasonably-close-to-correct HTML
  <h1>Select an Installation Directory</h1>
  The installation process builds libraries and copies headers into
  the following directory structure:
  
  <pre>
  <i>installation directory</i>
  |
  +---include
  |   |
  |   +---boost-<i>version</i>  <i>(e.g. boost-1_33/)</i> <b>&lt== the #include root</b>
  |       |
  |       +---boost        
  |           |
  |           +---<i>header1</i>.hpp
  |               <i>header2</i>.hpp
  |               .
  |               .
  |               . 
  |               <i>more headers and directories</i>
  |
  |
  +---lib
      |
      +---<i>library1</i>
          <i>library2</i>
          .
          .
          .
          
  </pre>
  The default installation directory is "/usr/local" on Unix systems
  and "C:\Boost" on Windows systems, but you can override that by
  passing <tt>--prefix=</tt><i>installation directory</i> on the
  <tt>bjam</tt> command line.
  <p> Note: the <b><code>#include</code> root</b> directory mentioned
  above will be added to your compiler's <code>#include</code> path in
  a later step.  If you don't install the Boost libraries because
  you're exclusively using its header-only libraries, the folder
  containing the downloaded Boost distribution will act as your
  <code>#include</code> root directory.
---
  The default build and install attempts to build all available
  libraries and install to default locations the libraries and Boost
  header files. On Unix systems the default install location is
  "/usr/local", and on Windows systems the default is
  "C:\Boost". Within those directories libraries are installed to the
  "lib" subdirectory, and headers to an "include/boost-1_32"
  subdirectory, the version will reflect the distribution you are
  installing.
This is really scary, after all the discussion of people not being
happy with the default installation location, because you have already
told people to go ahead and issue the commands that do the
installation!
Fortunately, all the important information went into the earlier
section, so you can strike that paragraph.  Just write
  If you need to change the installation directories or you want to
  tune other aspects of the build, see Configuring the Build.
here, as you have done, and it will be perfect.
---
Rename 
  Add the Boost root directory to the compiler's #include <...> path
to
  Tell the Compiler About the <code>#include</code> Root Directory
Rewrite the contents accordingly.
---
   If you are using an IDE, refer to its documentation how to do
   this. 
It's a nit, but we went over this issue already: as a point of style,
you can't use "this" without an antecedent, i.e. a noun after "this"
that describes what this refers to, as in "how to do this job."  But
don't say that; it's awkward.  I suggest you look for all instances of
"this" and check your usage.
Also, there's a preposition missing before "how."  How about,
  If you are using an IDE, there is usually a graphical tool for
  specifying which directories will be searched for
  <code>#include<...></code>ed files.
??
---
Footnotes: 
[1] Depending on your installation, a Unix compiler such as GCC may
    have additional requirements. Check with your system administrator
    if you're unsure about your installation.
-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com

Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk