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
but it should be
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.  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><== 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:  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