Getting started build section
Dave, I am reading the getting started guide, and think some of the build instructions can be improved. I can do this myself, if we agree on the nature of the changes. For reference, I'm looking at: http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html 5 Prepare to Use a Boost Library Binary I think the section title is too long-winded. "Prepare" does not even suggest any kind of building. And of course, we have many libraries, so saying "a ... Binary" is not accurate. Would "Building Library Binaries" be more to the point? The installers supplied by BoostPro Computing will download and install pre-compiled binaries into the lib\ subdirectory of the boost root, typically C:\Program Files\boost\boost_1_37_0\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. I can't understand what the second sentence say. If installer allows to install only some variants of Boost.Regex, then documentation should to request the user to run the installer again, and install the remaining ones. I can't fix this text without knowing what it means. 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. Earlier than what? No version of Visual C++ is mentioned in the preceding text. Boost.Build is a text-based system for developing, testing, and installing software. To use it, you'll need an executable called 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. The last sentence of 5.2 and the first sentence of 5.2.1 essentially duplicate each other. Besides, bjam does not really drives Boost.Build (just like my car does not drive me, usually). First, find the toolset corresponding to your compiler in the following table. The kylix should be removed from the table. "FreeScale" should be "Freescale". This should also link to the list of toolchains in Boost.Build docs. 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 default Boost.Build will create a bin.v2/ subdirectory for that purpose in your current working directory. I suggest that this section be dropped. In describes a non-mainstream usage that is better be describe elsewhere. FWIW, the case of building source straight from CD does not seem reasonable, since with large number of headers the performance will be horrible. Likewise, building from a network drive is not a good idea. So, copying source to a local drive and building from there is the best thing. bjam --build-dir=build-directory --toolset=toolset-name --build-type=complete stage Per above, I suggest we drop --build-dir. --toolset= should become toolset= This section should also link to Boost.Build doc section about command line syntax. 5.3 Expected Build Output This section fails to mention the single most important point -- that the libraries are produced, and where they are produced. In fact, I don't see an obvious purpose of this section to the user -- it just says "oh, and those kinds of message appear". This section fails to explain what is produced as result -- like that libraries will be placed in the 'stage' directory. I'd suggest rewording the section like this: 5.3 Interpreting the results. The build process produces a large number of output during compilation, including diagnostic messages from Boost.Build, names of files being compiled and messages from the compiler. A summary is printed at the end. If the summary does not include any failed targets, your build is successful, and the library binaries can be found in the 'stage' directory. Otherwise, you can browse the output to see which libraries failed to build, and which compile errors were produced. You can also run bjam again, with the same option, to try compiling the failed files again. A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because of lack of required third party libraries. You might want to check that you don't require the disabled functionality, and perform additional configuration (see individual libraries documentation). If it seems like the build system can't find your compiler and/or linker, consider setting up a user-config.jam file as described in the Boost.Build documentation. This should have a link to Boost.Build section about configuration, not to the top-level docs. Comments? - Volodya
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
Dave, I am reading the getting started guide, and think some of the build instructions can be improved. I can do this myself, if we agree on the nature of the changes.
For reference, I'm looking at:
http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html
5 Prepare to Use a Boost Library Binary
I think the section title is too long-winded. "Prepare" does not even suggest any kind of building. And of course, we have many libraries, so saying "a ... Binary" is not accurate. Would "Building Library Binaries" be more to the point?
No. You may have used the installer.
The installers supplied by BoostPro Computing will download and install pre-compiled binaries into the lib\ subdirectory of the boost root, typically C:\Program Files\boost\boost_1_37_0\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.
I can't understand what the second sentence say. If installer allows to install only some variants of Boost.Regex, then documentation should to request the user to run the installer again, and install the remaining ones. I can't fix this text without knowing what it means.
Umm, that's exactly what it means. There's nothing to fix.
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.
Earlier than what? No version of Visual C++ is mentioned in the preceding text.
Good point;
Boost.Build is a text-based system for developing, testing, and installing software. To use it, you'll need an executable called 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.
The last sentence of 5.2 and the first sentence of 5.2.1 essentially duplicate each other.
No; 5.2.1 makes it clear you'll be using bjam from the command-line and explains its role in the process. For example, it's not just something that sets up your environment or post-processes library files.
Besides, bjam does not really drives Boost.Build (just like my car does not drive me, usually).
Umm, right. Lots of terms we use in CS don't map meaningfully onto everyday objects. How would you characterize bjam's role in the system?
First, find the toolset corresponding to your compiler in the following table.
The kylix should be removed from the table.
Have we dropped it?
"FreeScale" should be "Freescale".
Good point;
This should also link to the list of toolchains in Boost.Build docs.
Exact link, please.
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 default Boost.Build will create a bin.v2/ subdirectory for that purpose in your current working directory.
I suggest that this section be dropped. In describes a non-mainstream usage that is better be describe elsewhere.
Maybe, but the thing I worry about is that a suitable "elsewhere" doesn't exist. People seem to expect the GSG to tell them all sorts of things that perhaps should be in a Boost.Build guide. I think that's because they are having a hard time making the jump to that documentation.
FWIW, the case of building source straight from CD does not seem reasonable, since with large number of headers the performance will be horrible.
True.
Likewise, building from a network drive is not a good idea.
Why? I know companies where people do that successfully.
So, copying source to a local drive and building from there is the best thing.
bjam --build-dir=build-directory --toolset=toolset-name --build-type=complete stage
Per above, I suggest we drop --build-dir. --toolset= should become toolset=
Sorry, I thought I had changed the --toolset= business already.
This section should also link to Boost.Build doc section about command line syntax.
Exact link, please.
5.3 Expected Build Output
This section fails to mention the single most important point -- that the libraries are produced, and where they are produced. In fact, I don't see an obvious purpose of this section to the user -- it just says "oh, and those kinds of message appear".
The purpose is to help all the people who have told us over the years that they get gobs of messages and they don't know how to tell whether everything worked or not. People have been confused by the ICU and Python-related messages. People have been confused by the number of targets built/skipped messages. People have been confused and upset by the long pathnames they are seeing; at least telling them that they're normal eliminates much of that effect.
This section fails to explain what is produced as result -- like that libraries will be placed in the 'stage' directory.
That's certainly important.
I'd suggest rewording the section like this:
5.3 Interpreting the results.
I like the new section title.
The build process produces a large number of output during compilation, including diagnostic messages from Boost.Build, names of files being compiled and messages from the compiler. A summary is printed at the end.
I would want to clarify "a summary is printed at the end" so the reader doesn't think we mean that we summarize these messages at the end of the document she is reading.
If the summary does not include any failed targets, your build is successful, and the library binaries can be found in the 'stage' directory.
"the 'stage' directory" is too imprecise. How will the reader find it?
Otherwise, you can browse the output to see which libraries failed to build, and which compile errors were produced. You can also run bjam again, with the same option, to try compiling the failed files again.
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because of lack of required third party libraries.
I think lacking a 3rd-party library is not the only reason the functionality might be disabled. Don't you need some environment variables set for ICU, or something?
You might want to check that you don't require the disabled functionality, and perform additional configuration (see individual libraries documentation).
If it seems like the build system can't find your compiler and/or linker, consider setting up a user-config.jam file as described in the Boost.Build documentation.
Exact link please.
This should have a link to Boost.Build section about configuration, not to the top-level docs.
I think you raise a number of good points above. Certainly I welcome more participation from the Boost.Build team in ensuring a smooth Getting Started experience. In particular, I think helping people transition from the GSG to the Boost.Build documentation is crucial. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
On Thursday 06 November 2008 17:38:02 David Abrahams wrote:
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
Dave, I am reading the getting started guide, and think some of the build instructions can be improved. I can do this myself, if we agree on the nature of the changes.
For reference, I'm looking at:
http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html
5 Prepare to Use a Boost Library Binary
I think the section title is too long-winded. "Prepare" does not even suggest any kind of building. And of course, we have many libraries, so saying "a ... Binary" is not accurate. Would "Building Library Binaries" be more to the point?
No. You may have used the installer.
And what about "a ... Binary" being not accurate, given that there's lots of library binaries?
The installers supplied by BoostPro Computing will download and install pre-compiled binaries into the lib\ subdirectory of the boost root, typically C:\Program Files\boost\boost_1_37_0\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.
I can't understand what the second sentence say. If installer allows to install only some variants of Boost.Regex, then documentation should to request the user to run the installer again, and install the remaining ones. I can't fix this text without knowing what it means.
Umm, that's exactly what it means. There's nothing to fix.
If you want to say that users should always install all variants of Boost.Regex, please say so. Instructing the user to run installer again, and then select all variants, seems to have no benefits over selecting all variants in the first place. Am I missing something?
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.
Earlier than what? No version of Visual C++ is mentioned in the preceding text.
Good point;
Boost.Build is a text-based system for developing, testing, and installing software. To use it, you'll need an executable called 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.
The last sentence of 5.2 and the first sentence of 5.2.1 essentially duplicate each other.
No; 5.2.1 makes it clear you'll be using bjam from the command-line and explains its role in the process. For example, it's not just something that sets up your environment or post-processes library files.
Besides, bjam does not really drives Boost.Build (just like my car does not drive me, usually).
Umm, right. Lots of terms we use in CS don't map meaningfully onto everyday objects. How would you characterize bjam's role in the system?
I would not try, actually. For most users, bjam and Boost.Build are not independent projects, so saying that Boost.Build is invoked by typing bjam on the command line seems reasonable.
First, find the toolset corresponding to your compiler in the following table.
The kylix should be removed from the table.
Have we dropped it?
Years ago (the product is dead, nobody used the Boost.Build support either)
"FreeScale" should be "Freescale".
Good point;
This should also link to the list of toolchains in Boost.Build docs.
Exact link, please.
http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html
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 default Boost.Build will create a bin.v2/ subdirectory for that purpose in your current working directory.
I suggest that this section be dropped. In describes a non-mainstream usage that is better be describe elsewhere.
Maybe, but the thing I worry about is that a suitable "elsewhere" doesn't exist. People seem to expect the GSG to tell them all sorts of things that perhaps should be in a Boost.Build guide. I think that's because they are having a hard time making the jump to that documentation.
If you add a link to Boost.Build command line, that's where --build-dir is documented: http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html
FWIW, the case of building source straight from CD does not seem reasonable, since with large number of headers the performance will be horrible.
True.
Likewise, building from a network drive is not a good idea.
Why? I know companies where people do that successfully.
I presume this depends on exact network infrastructure and usage scenarios, but a couple of couple of 8-core servers compiling from network disk can bring down a decent storage solution quite easily.
So, copying source to a local drive and building from there is the best thing.
bjam --build-dir=build-directory --toolset=toolset-name --build-type=complete stage
Per above, I suggest we drop --build-dir. --toolset= should become toolset=
Sorry, I thought I had changed the --toolset= business already.
This section should also link to Boost.Build doc section about command line syntax.
Exact link, please.
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html
5.3 Expected Build Output
This section fails to mention the single most important point -- that the libraries are produced, and where they are produced. In fact, I don't see an obvious purpose of this section to the user -- it just says "oh, and those kinds of message appear".
The purpose is to help all the people who have told us over the years that they get gobs of messages and they don't know how to tell whether everything worked or not. People have been confused by the ICU and Python-related messages. People have been confused by the number of targets built/skipped messages. People have been confused and upset by the long pathnames they are seeing; at least telling them that they're normal eliminates much of that effect.
This section fails to explain what is produced as result -- like that libraries will be placed in the 'stage' directory.
That's certainly important.
I'd suggest rewording the section like this:
5.3 Interpreting the results.
I like the new section title.
The build process produces a large number of output during compilation, including diagnostic messages from Boost.Build, names of files being compiled and messages from the compiler. A summary is printed at the end.
I would want to clarify "a summary is printed at the end" so the reader doesn't think we mean that we summarize these messages at the end of the document she is reading.
If the summary does not include any failed targets, your build is successful, and the library binaries can be found in the 'stage' directory.
"the 'stage' directory" is too imprecise. How will the reader find it?
If no --stagedir option is given, the 'stage' directory is placed in boost source root and named 'stage', exactly. That's what I meant. In fact, this post is prompted by user report on boost-build that say we don't document --stagedir. The --stagedir is an option defined in Boost Jamroot, not in Boost.Build, so probably should be documented. Though relying on bjam --help output may be acceptable, too.
Otherwise, you can browse the output to see which libraries failed to build, and which compile errors were produced. You can also run bjam again, with the same option, to try compiling the failed files again.
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because of lack of required third party libraries.
I think lacking a 3rd-party library is not the only reason the functionality might be disabled. Don't you need some environment variables set for ICU, or something?
Ok, not "lack", then: A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because the required third party libraries could not be found.
You might want to check that you don't require the disabled functionality, and perform additional configuration (see individual libraries documentation).
If it seems like the build system can't find your compiler and/or linker, consider setting up a user-config.jam file as described in the Boost.Build documentation.
Exact link please.
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html
This should have a link to Boost.Build section about configuration, not to the top-level docs.
I think you raise a number of good points above. Certainly I welcome more participation from the Boost.Build team in ensuring a smooth Getting Started experience. In particular, I think helping people transition from the GSG to the Boost.Build documentation is crucial.
I fully agree. Note that some of the links I gave above are to recently-updated sections, meant to give a relatively complete instructions to somebody who just wants to build boost with slightly custom settings. - Volodya
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
On Thursday 06 November 2008 17:38:02 David Abrahams wrote:
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
Dave, I am reading the getting started guide, and think some of the build instructions can be improved. I can do this myself, if we agree on the nature of the changes.
For reference, I'm looking at:
http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html> > 5 Prepare to Use a Boost Library Binary
I think the section title is too long-winded. "Prepare" does not even suggest any kind of building. And of course, we have many libraries, so saying "a ... Binary" is not accurate. Would "Building Library Binaries" be more to the point?
No. You may have used the installer.
And what about "a ... Binary" being not accurate, given that there's lots of library binaries?
It *is* accurate. We're working on a single example, and to build/run that example you need a library binary, and this section describes what you need to do to prepare to use it.
The installers supplied by BoostPro Computing will download and install pre-compiled binaries into the lib\ subdirectory of the boost root, typically C:\Program Files\boost\boost_1_37_0\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.
I can't understand what the second sentence say. If installer allows to install only some variants of Boost.Regex, then documentation should to request the user to run the installer again, and install the remaining ones. I can't fix this text without knowing what it means.
Umm, that's exactly what it means. There's nothing to fix.
If you want to say that users should always install all variants of Boost.Regex, please say so.
That's not what I want to say.
Instructing the user to run installer again, and then select all variants, seems to have no benefits over selecting all variants in the first place. Am I missing something?
People who know they don't need binaries based on earlier sections of the document shouldn't be instructed to build and install them from the beginning.
The last sentence of 5.2 and the first sentence of 5.2.1 essentially duplicate each other.
No; 5.2.1 makes it clear you'll be using bjam from the command-line and explains its role in the process. For example, it's not just something that sets up your environment or post-processes library files.
Besides, bjam does not really drives Boost.Build (just like my car does not drive me, usually).
Umm, right. Lots of terms we use in CS don't map meaningfully onto everyday objects. How would you characterize bjam's role in the system?
I would not try, actually. For most users, bjam and Boost.Build are not independent projects, so saying that Boost.Build is invoked by typing bjam on the command line seems reasonable.
I was trying to make the distinction and relationship between bjam and Boost.Build a little clearer. I think you may be forgetting the many people who used to say, "I read all through the bjam documentation but I can't figure out how to <do something that's Boost.Build functionality>"
First, find the toolset corresponding to your compiler in the following table. The kylix should be removed from the table.
Have we dropped it?
Years ago (the product is dead, nobody used the Boost.Build support either)
OK.
"FreeScale" should be "Freescale".
Good point;
This should also link to the list of toolchains in Boost.Build docs.
Exact link, please.
http://www.boost.org/boost-build2/doc/html/bbv2/reference/tools.html
Thanks.
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 default Boost.Build will create a bin.v2/ subdirectory for that purpose in your current working directory.
I suggest that this section be dropped. In describes a non-mainstream usage that is better be describe elsewhere.
Maybe, but the thing I worry about is that a suitable "elsewhere" doesn't exist. People seem to expect the GSG to tell them all sorts of things that perhaps should be in a Boost.Build guide. I think that's because they are having a hard time making the jump to that documentation.
If you add a link to Boost.Build command line, that's where --build-dir is documented:
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html
IMO the description of build-dir there is unsuitable for a beginning user who doesn't know what these terms really mean: "project roots" "Jamroot files" "declare project name" "the project name specified in Jamroot" "build dir specified in Jamroot" That might be OK if --build-dir is a truly esoteric option that almost nobody needs. Now that we put everything under bin.v2, that might be true. It certainly wasn't true with BBv1, where targets were always built inside project directories by default. I'd like to hear some other peoples' opinions on whether it's still relevant.
Likewise, building from a network drive is not a good idea.
Why? I know companies where people do that successfully.
I presume this depends on exact network infrastructure and usage scenarios, but a couple of couple of 8-core servers compiling from network disk can bring down a decent storage solution quite easily.
I trust people to evaluate whether that's suitable for them. Most people will indeed have the sources on a local disk.
This section should also link to Boost.Build doc section about command line syntax.
Exact link, please.
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html
Thanks.
If the summary does not include any failed targets, your build is successful, and the library binaries can be found in the 'stage' directory.
"the 'stage' directory" is too imprecise. How will the reader find it?
If no --stagedir option is given, the 'stage' directory is placed in boost source root and named 'stage', exactly. That's what I meant. In fact, this post is prompted by user report on boost-build that say we don't document --stagedir. The --stagedir is an option defined in Boost Jamroot, not in Boost.Build, so probably should be documented. Though relying on bjam --help output may be acceptable, too.
--stagedir and --build-dir are very similar. We should probably make the same decision about documenting both of them.
Otherwise, you can browse the output to see which libraries failed to build, and which compile errors were produced. You can also run bjam again, with the same option, to try compiling the failed files again.
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because of lack of required third party libraries.
I think lacking a 3rd-party library is not the only reason the functionality might be disabled. Don't you need some environment variables set for ICU, or something?
Ok, not "lack", then:
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because the required third party libraries could not be found.
Personally I don't see how this improves on the text that I already wrote covering this topic. Nobody has reported confusion about that text.
You might want to check that you don't require the disabled functionality, and perform additional configuration (see individual libraries documentation).
If it seems like the build system can't find your compiler and/or linker, consider setting up a user-config.jam file as described in the Boost.Build documentation.
Exact link please.
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html
Thanks.
This should have a link to Boost.Build section about configuration, not to the top-level docs.
I think you raise a number of good points above. Certainly I welcome more participation from the Boost.Build team in ensuring a smooth Getting Started experience. In particular, I think helping people transition from the GSG to the Boost.Build documentation is crucial.
I fully agree. Note that some of the links I gave above are to recently-updated sections, meant to give a relatively complete instructions to somebody who just wants to build boost with slightly custom settings.
That's very encouraging news. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
AMDG David Abrahams wrote:
--stagedir and --build-dir are very similar. We should probably make the same decision about documenting both of them.
How similar are they really? build-dir primarily controls where all the intermediate files go. stagedir controls where the libraries get installed to. I would expect anyone who uses stage to care about where the libraries end up, even if the default is fine. In Christ, Steven Watanabe
on Thu Nov 06 2008, Steven Watanabe <watanabesj-AT-gmail.com> wrote:
AMDG
David Abrahams wrote:
--stagedir and --build-dir are very similar. We should probably make the same decision about documenting both of them.
How similar are they really?
build-dir primarily controls where all the intermediate files go. stagedir controls where the libraries get installed to. I would expect anyone who uses stage to care about where the libraries end up, even if the default is fine.
Okay, point taken. If there's going to be a default at all, I suppose Boost.Build should end by printing a message telling you where they've been installed... and probably begin by printing a message telling you where they *will* be instlaled. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
On Thursday 06 November 2008 19:55:33 David Abrahams wrote:
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
On Thursday 06 November 2008 17:38:02 David Abrahams wrote:
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
Dave, I am reading the getting started guide, and think some of the build instructions can be improved. I can do this myself, if we agree on the nature of the changes.
For reference, I'm looking at:
http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html> > 5 Prepare to Use a Boost Library Binary
I think the section title is too long-winded. "Prepare" does not even suggest any kind of building. And of course, we have many libraries, so saying "a ... Binary" is not accurate. Would "Building Library Binaries" be more to the point?
No. You may have used the installer.
And what about "a ... Binary" being not accurate, given that there's lots of library binaries?
It *is* accurate. We're working on a single example, and to build/run that example you need a library binary, and this section describes what you need to do to prepare to use it.
Maybe it's just me, but when I start doing anything with a new tool or library, the first thing I do is to build all of it. Cherry-picking specific libraries is less common use-case.
The installers supplied by BoostPro Computing will download and install pre-compiled binaries into the lib\ subdirectory of the boost root, typically C:\Program Files\boost\boost_1_37_0\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.
I can't understand what the second sentence say. If installer allows to install only some variants of Boost.Regex, then documentation should to request the user to run the installer again, and install the remaining ones. I can't fix this text without knowing what it means.
Umm, that's exactly what it means. There's nothing to fix.
If you want to say that users should always install all variants of Boost.Regex, please say so.
That's not what I want to say.
Instructing the user to run installer again, and then select all variants, seems to have no benefits over selecting all variants in the first place. Am I missing something?
People who know they don't need binaries based on earlier sections of the document shouldn't be instructed to build and install them from the beginning.
Oh, you mean that the first section of the document say this: To complete this tutorial, you'll need to at least install the Static Multithreaded variants of the Boost.Regex binaries when given the option. I think there are some problems with the text in section 5, still: - It demands that you install *all* variants of Boost.Regex, while the above say only one variant is necessary. - Many users will jump straight to section 5 (e.g. because they just want to get Boost libraries, and are not interested in preceding sections). Or even if they read section 1, at this point they already forgotten that Boost.Regex is going to be used in example. And they were not instructed, previously, to run the installer. So, this passage can be interpreted as asking the user to run the installer twice -- which is how I've interpreted it.
The last sentence of 5.2 and the first sentence of 5.2.1 essentially duplicate each other.
No; 5.2.1 makes it clear you'll be using bjam from the command-line and explains its role in the process. For example, it's not just something that sets up your environment or post-processes library files.
Besides, bjam does not really drives Boost.Build (just like my car does not drive me, usually).
Umm, right. Lots of terms we use in CS don't map meaningfully onto everyday objects. How would you characterize bjam's role in the system?
I would not try, actually. For most users, bjam and Boost.Build are not independent projects, so saying that Boost.Build is invoked by typing bjam on the command line seems reasonable.
I was trying to make the distinction and relationship between bjam and Boost.Build a little clearer. I think you may be forgetting the many people who used to say, "I read all through the bjam documentation but I can't figure out how to <do something that's Boost.Build functionality>"
I think this problem better solved by giving pointers to Boost.Build docs, and generally stressing that "bjam" is just the command-line name of Boost.Build.
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 default Boost.Build will create a bin.v2/ subdirectory for that purpose in your current working directory.
I suggest that this section be dropped. In describes a non-mainstream usage that is better be describe elsewhere.
Maybe, but the thing I worry about is that a suitable "elsewhere" doesn't exist. People seem to expect the GSG to tell them all sorts of things that perhaps should be in a Boost.Build guide. I think that's because they are having a hard time making the jump to that documentation.
If you add a link to Boost.Build command line, that's where --build-dir is documented:
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html
IMO the description of build-dir there is unsuitable for a beginning user who doesn't know what these terms really mean:
"project roots" "Jamroot files" "declare project name" "the project name specified in Jamroot" "build dir specified in Jamroot"
That might be OK if --build-dir is a truly esoteric option that almost nobody needs. Now that we put everything under bin.v2, that might be true. It certainly wasn't true with BBv1, where targets were always built inside project directories by default. I'd like to hear some other peoples' opinions on whether it's still relevant.
FWIW, I've filed an issue to improve --build-dir docs.
If the summary does not include any failed targets, your build is successful, and the library binaries can be found in the 'stage' directory.
"the 'stage' directory" is too imprecise. How will the reader find it?
If no --stagedir option is given, the 'stage' directory is placed in boost source root and named 'stage', exactly. That's what I meant. In fact, this post is prompted by user report on boost-build that say we don't document --stagedir. The --stagedir is an option defined in Boost Jamroot, not in Boost.Build, so probably should be documented. Though relying on bjam --help output may be acceptable, too.
--stagedir and --build-dir are very similar. We should probably make the same decision about documenting both of them.
I agree with Steven, --stagedir controls where the build results go, so users need to know about it. --build-dir controls where intermediate products go, so it's rarely used option.
Otherwise, you can browse the output to see which libraries failed to build, and which compile errors were produced. You can also run bjam again, with the same option, to try compiling the failed files again.
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because of lack of required third party libraries.
I think lacking a 3rd-party library is not the only reason the functionality might be disabled. Don't you need some environment variables set for ICU, or something?
Ok, not "lack", then:
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because the required third party libraries could not be found.
Personally I don't see how this improves on the text that I already wrote covering this topic. Nobody has reported confusion about that text.
I'd personally be happy with any wording for this section that: 1. Emphasized how user can know if the build is successful, and how to diagnose the problems. E.g. many users, on IRC, fail to report actual compiler errors, or compiler commands and instead report the "failed XXX" message from Boost.Build. Also, where to look for results of the build. 2. Emphasizes that if there are no errors, the only thing user might care about is those configuration notices. The syntax of: toolset-name.c++ long/path/to/file/being/built is something, IMO, that need to be described at all. - Volodya
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
On Thursday 06 November 2008 19:55:33 David Abrahams wrote:
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
On Thursday 06 November 2008 17:38:02 David Abrahams wrote:
on Thu Nov 06 2008, Vladimir Prus <ghost-AT-cs.msu.su> wrote:
Dave, I am reading the getting started guide, and think some of the build instructions can be improved. I can do this myself, if we agree on the nature of the changes.
For reference, I'm looking at:
http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html> > 5 Prepare to Use a Boost Library Binary
I think the section title is too long-winded. "Prepare" does not even suggest any kind of building. And of course, we have many libraries, so saying "a ... Binary" is not accurate. Would "Building Library Binaries" be more to the point?
No. You may have used the installer.
And what about "a ... Binary" being not accurate, given that there's lots of library binaries?
It *is* accurate. We're working on a single example, and to build/run that example you need a library binary, and this section describes what you need to do to prepare to use it.
Maybe it's just me, but when I start doing anything with a new tool or library, the first thing I do is to build all of it. Cherry-picking specific libraries is less common use-case.
Even if I were to stipulate to that assertion, none of it bears on the accuracy of "a ... Binary" in the context of this tutorial. Every mind-numbingly-long step in a tutorial has a serious negative impact on learnability. Building all of Boost is really slow. Even downloading all the binaries with the installer can be slow.
People who know they don't need binaries based on earlier sections of the document shouldn't be instructed to build and install them from the beginning.
Oh, you mean that the first section of the document say this:
To complete this tutorial, you'll need to at least install the Static Multithreaded variants of the Boost.Regex binaries when given the option.
Yes.
I think there are some problems with the text in section 5, still:
- It demands that you install *all* variants of Boost.Regex, while the above say only one variant is necessary.
Good point.
- Many users will jump straight to section 5 (e.g. because they just want to get Boost libraries, and are not interested in preceding sections).
I don't believe you, but if so, they're in the wrong place. This is a getting started guide, not a "how to build boost" guide.
Or even if they read section 1, at this point they already forgotten that Boost.Regex is going to be used in example. And they were not instructed, previously, to run the installer. So, this passage can be interpreted as asking the user to run the installer twice -- which is how I've interpreted it.
It's simple. The passage says to re-run the installer if, the first time, you didn't select the options needed for the upcoming step. I don't understand what you're objecting to.
I would not try, actually. For most users, bjam and Boost.Build are not independent projects, so saying that Boost.Build is invoked by typing bjam on the command line seems reasonable.
I was trying to make the distinction and relationship between bjam and Boost.Build a little clearer. I think you may be forgetting the many people who used to say, "I read all through the bjam documentation but I can't figure out how to <do something that's Boost.Build functionality>"
I think this problem better solved by giving pointers to Boost.Build docs, and generally stressing that "bjam" is just the command-line name of Boost.Build.
I think you're forgetting all those people who pick it up and try to use it as "a better Perforce jam," expecting Boost.Build features and command-line options to be there. It can't be used as instructed without the BB sources, and that's very different from other binary build tools. I don't see a great advantage in changing this already-short text and the possible downsides are unattractive to me.
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 default Boost.Build will create a bin.v2/ subdirectory for that purpose in your current working directory.
I suggest that this section be dropped. In describes a non-mainstream usage that is better be describe elsewhere.
Maybe, but the thing I worry about is that a suitable "elsewhere" doesn't exist. People seem to expect the GSG to tell them all sorts of things that perhaps should be in a Boost.Build guide. I think that's because they are having a hard time making the jump to that documentation.
If you add a link to Boost.Build command line, that's where --build-dir is documented:
http://www.boost.org/boost-build2/doc/html/bbv2/advanced/invocation.html> IMO the description of build-dir there is unsuitable for a beginning user who doesn't know what these terms really mean:
"project roots" "Jamroot files" "declare project name" "the project name specified in Jamroot" "build dir specified in Jamroot"
That might be OK if --build-dir is a truly esoteric option that almost nobody needs. Now that we put everything under bin.v2, that might be true. It certainly wasn't true with BBv1, where targets were always built inside project directories by default. I'd like to hear some other peoples' opinions on whether it's still relevant.
FWIW, I've filed an issue to improve --build-dir docs.
OK, still waiting to hear from others before removing it from the GSG.
If the summary does not include any failed targets, your build is successful, and the library binaries can be found in the 'stage' directory.
"the 'stage' directory" is too imprecise. How will the reader find it?
If no --stagedir option is given, the 'stage' directory is placed in boost source root and named 'stage', exactly. That's what I meant. In fact, this post is prompted by user report on boost-build that say we don't document --stagedir. The --stagedir is an option defined in Boost Jamroot, not in Boost.Build, so probably should be documented. Though relying on bjam --help output may be acceptable, too.
--stagedir and --build-dir are very similar. We should probably make the same decision about documenting both of them.
I agree with Steven, --stagedir controls where the build results go, so users need to know about it. --build-dir controls where intermediate products go, so it's rarely used option.
People need to know how to get rid of those intermediate products. They're huge.
Ok, not "lack", then:
A the beginning of the build, you will be informed what functionality of C++ Boost libraries is disabled because the required third party libraries could not be found.
Personally I don't see how this improves on the text that I already wrote covering this topic. Nobody has reported confusion about that text.
I'd personally be happy with any wording for this section that:
1. Emphasized how user can know if the build is successful, and how to diagnose the problems. E.g. many users, on IRC, fail to report actual compiler errors, or compiler commands and instead report the "failed XXX" message from Boost.Build. Also, where to look for results of the build.
2. Emphasizes that if there are no errors, the only thing user might care about is those configuration notices. The syntax of:
toolset-name.c++ long/path/to/file/being/built
is something, IMO, that need to be described at all.
I disagree strongly unless we suppress those messages. People have repeatedly complained that they don't understand what it means when the tool spits out these messages. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
David Abrahams wrote:
- Many users will jump straight to section 5 (e.g. because they just want to get Boost libraries, and are not interested in preceding sections).
I don't believe you, but if so, they're in the wrong place. This is a getting started guide, not a "how to build boost" guide.
Oh, probably I've misunderstood the purpose of this text :-( So, you say we don't have any direct instructions how, given boost source, to end up with binaries for all libraries, and getting started is not meant to incorporate such instructions? Should we a separate document, then?
Or even if they read section 1, at this point they already forgotten that Boost.Regex is going to be used in example. And they were not instructed, previously, to run the installer. So, this passage can be interpreted as asking the user to run the installer twice -- which is how I've interpreted it.
It's simple. The passage says to re-run the installer if, the first time, you didn't select the options needed for the upcoming step. I don't understand what you're objecting to.
There's no "first time" previously in the document -- this the first time user is asked to run the installer.
I would not try, actually. For most users, bjam and Boost.Build are not independent projects, so saying that Boost.Build is invoked by typing bjam on the command line seems reasonable.
I was trying to make the distinction and relationship between bjam and Boost.Build a little clearer. I think you may be forgetting the many people who used to say, "I read all through the bjam documentation but I can't figure out how to <do something that's Boost.Build functionality>"
I think this problem better solved by giving pointers to Boost.Build docs, and generally stressing that "bjam" is just the command-line name of Boost.Build.
I think you're forgetting all those people who pick it up and try to use it as "a better Perforce jam," expecting Boost.Build features and command-line options to be there. It can't be used as instructed without the BB sources, and that's very different from other binary build tools. I don't see a great advantage in changing this already-short text and the possible downsides are unattractive to me.
Getting started clearly cannot accurately explain the relation between bjam and Boost.Build, so all that's needed is a sentence to get users going without creating false impressions. I think "bjam drives Boost.Build" is factually incorrect. Possible different wordings are: "Boost.Build is invoked by typing 'bjam' on the command line", or "bjam is the underlying build engine for Boost.Build" or something like that. Of course, this is not the most important issue.
I'd personally be happy with any wording for this section that:
1. Emphasized how user can know if the build is successful, and how to diagnose the problems. E.g. many users, on IRC, fail to report actual compiler errors, or compiler commands and instead report the "failed XXX" message from Boost.Build. Also, where to look for results of the build.
2. Emphasizes that if there are no errors, the only thing user might care about is those configuration notices. The syntax of:
toolset-name.c++ long/path/to/file/being/built
is something, IMO, that need to be described at all.
I disagree strongly unless we suppress those messages. People have repeatedly complained that they don't understand what it means when the tool spits out these messages.
Ok, I'm don't very much mind about leaving it, but it would be great if (1) and (2) are addressed. Where do we go from here? We've agreed on some points, and disagreed on others. Are you planning to act on the agreed points, or want me to? I realize you might not have time right away, but would be great to have this cleaned up for the next release. Thanks, Volodya
on Thu Nov 06 2008, Vladimir Prus <vladimir-AT-codesourcery.com> wrote:
David Abrahams wrote:
- Many users will jump straight to section 5 (e.g. because they just want to get Boost libraries, and are not interested in preceding sections).
I don't believe you, but if so, they're in the wrong place. This is a getting started guide, not a "how to build boost" guide.
Oh, probably I've misunderstood the purpose of this text :-( So, you say we don't have any direct instructions how, given boost source, to end up with binaries for all libraries, and getting started is not meant to incorporate such instructions?
That's just not a goal of that document.
Should we a separate document, then?
Not necessarily. If only a small change is required in order to present that information, it would be fine to add it. However, I would not want to do anything that would make it harder to use the GSG for its intended purpose. Also, note that everybody has his own pet "little thing" that should be added to the GSG (how to compile 64-bit targets, how to turn off library name gristing,...) so I have to be cautious even about smallish changes, or the document will become too complex via accretion.
Or even if they read section 1, at this point they already forgotten that Boost.Regex is going to be used in example. And they were not instructed, previously, to run the installer. So, this passage can be interpreted as asking the user to run the installer twice -- which is how I've interpreted it.
It's simple. The passage says to re-run the installer if, the first time, you didn't select the options needed for the upcoming step. I don't understand what you're objecting to.
There's no "first time" previously in the document -- this the first time user is asked to run the installer.
http://www.boost.org/doc/libs/1_37_0/more/getting_started/windows.html#get-b... seems to give a pretty clear encouragement to do just that.
I think you're forgetting all those people who pick it up and try to use it as "a better Perforce jam," expecting Boost.Build features and command-line options to be there. It can't be used as instructed without the BB sources, and that's very different from other binary build tools. I don't see a great advantage in changing this already-short text and the possible downsides are unattractive to me.
Getting started clearly cannot accurately explain the relation between bjam and Boost.Build, so all that's needed is a sentence to get users going without creating false impressions. I think "bjam drives Boost.Build" is factually incorrect. Possible different wordings are:
"Boost.Build is invoked by typing 'bjam' on the command line",
or
"bjam is the underlying build engine for Boost.Build"
or something like that.
Fine, I'll take the latter, and delete "build" from "build engine" :-)
Of course, this is not the most important issue.
No, it's not very important.
I'd personally be happy with any wording for this section that:
1. Emphasized how user can know if the build is successful, and how to diagnose the problems. E.g. many users, on IRC, fail to report actual compiler errors, or compiler commands and instead report the "failed XXX" message from Boost.Build. Also, where to look for results of the build.
2. Emphasizes that if there are no errors, the only thing user might care about is those configuration notices. The syntax of:
toolset-name.c++ long/path/to/file/being/built
is something, IMO, that need to be described at all.
I disagree strongly unless we suppress those messages. People have repeatedly complained that they don't understand what it means when the tool spits out these messages.
Ok, I'm don't very much mind about leaving it, but it would be great if (1) and (2) are addressed.
I agree that those are important.
Where do we go from here? We've agreed on some points, and disagreed on others. Are you planning to act on the agreed points, or want me to? I realize you might not have time right away, but would be great to have this cleaned up for the next release.
I definitely don't have time right away, and I agree it should be done for the next release. Perhaps you could summarize our points of agreement in a ticket? -- Dave Abrahams BoostPro Computing http://www.boostpro.com
participants (4)
-
David Abrahams -
Steven Watanabe -
Vladimir Prus -
Vladimir Prus