Getting started guide updates
Folks, I've tried to update the getting started guide (for Unix so far) to better explain building, in particular: - To make the "bootstrap + bjam" process the only documented one, since it turns out to be fairly painless on Unix - To clarify some common questions inline The result can be previewed at http://lvk.cs.msu.su/~ghost/unix-variants.pdf , see section 5. I would appreciate if folks take a look and suggest whether it can be improved further. I plan to make a similar update for Windows, but it's somewhat tricker. Thanks, -- Vladimir Prus Mentor Graphics +7 (812) 677-68-40
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Sunday, March 20, 2011 10:49 AM To: boost@lists.boost.org Subject: [boost] Getting started guide updates
I've tried to update the getting started guide (for Unix so far) to better explain building, in particular:
- To make the "bootstrap + bjam" process the only documented one, since it turns out to be fairly painless on Unix - To clarify some common questions inline
The result can be previewed at http://lvk.cs.msu.su/~ghost/unix-variants.pdf , see section 5. I would appreciate if folks take a look and suggest whether it can be improved further.
1 This looks better but it doesn't have an index. However this PDF version is *much* better because one can search for words/phrases. 2 Yet more examples would be even more helpful. No everyone will remember/RTFM to realise that italics mean 'your choice here', so be explicit? For example, unless you are going to automatically update the version number , it would be clearer to write " 1 download (probably latest) Boost version package, boost_1_version_1.tar.bz2 ('version' in italics of course) for example, boost_1_46_1.tar.bz2 " or #include <boost/whatever.hpp> for example: #include <boost/lambda/lambda.hpp> and many others too. 3 "boost root directory - called $BOOST_ROOT" 4 A *much* bigger collection of examples of building command lines would be even better. 5 Would a collection of command files .sh (or .bat for MS) be even better? 6 Amusing typo - "To save complication time," should be "compliation" ? ;-) 7 Queries should a widespread confusion about which items (options) need -- and which (properties) don't. A table of both of these, or a link to them (in Boost.Build documentation) would reduce this confusion greatly. But there is no substitute for *examples* - people hate to RTFM! 8 Sending a log file should be 'standard' and shown in most of the examples?
I plan to make a similar update for Windows, but it's somewhat trickier.
but even more important as MicroSofties tend to be less comfortable with command line stuff ;-) Thanks Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Max Sobolev Sent: Monday, March 21, 2011 7:41 AM To: boost@lists.boost.org Subject: Re: [boost] Getting started guide updates
On 20.03.2011 15:49, Paul A. Bristow wrote:
6 Amusing typo - "To save complication time," should be "compliation" ? ;-)
..but "compliation" in turn should be "compilation"?
Ok - touché! (and this was after I corrected it from mis-typing "complication"! why can't these computers type what I mean and not what I type?) Paul
On Sun, Mar 20, 2011 at 5:49 AM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Sunday, March 20, 2011 10:49 AM To: boost@lists.boost.org Subject: [boost] Getting started guide updates
I've tried to update the getting started guide (for Unix so far) to better explain building,
If you're doing this the "right" way, by editing the ReST source, most of the changes will be in common files and much of the Windows instructions will update appropriately.
2 Yet more examples would be even more helpful.
No everyone will remember/RTFM to realise that italics mean 'your choice here', so be explicit?
For example, unless you are going to automatically update the version number , it would be clearer to write
" 1 download (probably latest) Boost version package, boost_1_version_1.tar.bz2 ('version' in italics of course)
for example, boost_1_46_1.tar.bz2 "
or
#include <boost/whatever.hpp>
for example: #include <boost/lambda/lambda.hpp>
and many others too.
+1. These would be useful changes.
3 "boost root directory - called $BOOST_ROOT"
I don't understand this comment.
4 A *much* bigger collection of examples of building command lines would be even better.
Yes, with the caveat that this should remain a *Getting Started* guide. Information for less-common usage must not obscure the information that the newbie needs.
5 Would a collection of command files .sh (or .bat for MS) be even better?
I don't understand this comment.
7 Queries should a widespread confusion about which items (options) need -- and which (properties) don't.
Nor this one.
A table of both of these, or a link to them (in Boost.Build documentation) would reduce this confusion greatly.
But there is no substitute for *examples* - people hate to RTFM!
8 Sending a log file should be 'standard' and shown in most of the examples?
Sending it where? -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Dave Abrahams wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Sunday, March 20, 2011 10:49 AM To: boost@lists.boost.org Subject: [boost] Getting started guide updates
I've tried to update the getting started guide (for Unix so far) to better explain building,
If you're doing this the "right" way, by editing the ReST source, most of the changes will be in common files and much of the Windows instructions will update appropriately.
I am editing the source -- but that won't magically write descriptions how to specify version of msvc and how they are found, nor what to do if you have mingw, nor anything like that. - Volodya -- Vladimir Prus Mentor Graphics +7 (812) 677-68-40
At Tue, 22 Mar 2011 11:43:20 +0300, Vladimir Prus wrote:
Dave Abrahams wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Sunday, March 20, 2011 10:49 AM To: boost@lists.boost.org Subject: [boost] Getting started guide updates
I've tried to update the getting started guide (for Unix so far) to better explain building,
If you're doing this the "right" way, by editing the ReST source, most of the changes will be in common files and much of the Windows instructions will update appropriately.
I am editing the source -- but that won't magically write descriptions how to specify version of msvc and how they are found, nor what to do if you have mingw, nor anything like that.
'Course not. I'm just trying to pre-empt what I've seen earlier where someone finds the HTML and starts hacking at it directly. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
At Tue, 22 Mar 2011 11:43:20 +0300, Vladimir Prus wrote:
Dave Abrahams wrote:
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Vladimir Prus Sent: Sunday, March 20, 2011 10:49 AM To: boost@lists.boost.org Subject: [boost] Getting started guide updates
I've tried to update the getting started guide (for Unix so far) to better explain building,
If you're doing this the "right" way, by editing the ReST source, most of the changes will be in common files and much of the Windows instructions will update appropriately.
I am editing the source -- but that won't magically write descriptions how to specify version of msvc and how they are found, nor what to do if you have mingw, nor anything like that.
'Course not. I'm just trying to pre-empt what I've seen earlier where someone finds the HTML and starts hacking at it directly. Thanks for reassuring me. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Hi Vladimir, The document looks really good! On Sun, Mar 20, 2011 at 01:48:41PM +0300, Vladimir Prus wrote:
- To make the "bootstrap + bjam" process the only documented one, since it turns out to be fairly painless on Unix
Yes, bootstrap.sh has really improved building boost.
The result can be previewed at http://lvk.cs.msu.su/~ghost/unix-variants.pdf , see section 5. I would appreciate if folks take a look and suggest whether it can be improved further.
Reading through Section 5.1, I stumbled over specifying "toolset=gcc-4.5", whereas the C++ compiler name is really "g++-4.5". The first line in this section mentions "... default compiler, typically g++" whereas the 4th line says "... command gcc-4.5 works". But gcc-4.5 is not the C++ compiler, it is g++-4.5. Is it true that bjam is smart enough to use g++-4.5 in this case? If so, it's worth clarifying that I wouldn't have to edit project-config.jam in this case. Small comment for Section 5.3: "--build-dir, option that specifies where intermediate build products should be placed". It controls also where the final libraries are placed, I imagine. Perhaps drop "intermediate". Also, you don't need a comma after --build-dir. Overall, this is a really good introduction for someone using the source distribution of Boost. Footnote 1 invites Boost packagers to help ensure the instructions can be used with their packages. However, the document intertwines using Boost to build a program (Sections 4 and 6) with description of the source layout and building Boost itself (Sections 2, 3, 5). This is very natural for someone who just downloaded the boost sources but is not the emphasis I'd place if I were writing this for Debian. For a Debian user getting started with Boost, I would replace "1 Get Boost" with a description of the Debian package structure. I would need only the "Header Organization" box from Section 2. I would remove Section 5 entirely. In Section 6 I would emphasize the "layout=system" library naming and mention the fully-decorated naming in passing. And, of course, the -I and -L options are unnecessary as is setting LD_LIBRARY_PATH. Etc. Is your goal that a single document encompass the source distribution and, say, the Debian distribution? Cheers, -Steve
participants (5)
-
Dave Abrahams -
Max Sobolev -
Paul A. Bristow -
Steve M. Robbins -
Vladimir Prus