I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated. I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst -- Dave Abrahams Boost Consulting www.boost-consulting.com
Maybe it's just me, but I can't seem to download the attachment. David Abrahams wrote:
I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated.
I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst
------------------------------------------------------------------------
------------------------------------------------------------------------
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Andrew Schweitzer <a.schweitzer.grps@gmail.com> writes:
Maybe it's just me, but I can't seem to download the attachment.
Gah, I think the list may have stripped it. Enclosed again, but just in case: http://boost.cvs.sourceforge.net/*checkout*/boost/boost/more/getting_started... NOTE: if you simply follow this link instead of downloading it, your browser will probably display something garbled because the webserver is an old version of Apache that can't handle utf-8. Download the file to your disk instead (starting at http://boost.cvs.sourceforge.net/boost/boost/more/getting_started.html?view=... might be easier) and then view the file. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams <dave@boost-consulting.com> writes:
Maybe it's just me, but I can't seem to download the attachment.
Gah, I think the list may have stripped it. Enclosed again, but just in case:
http://boost.cvs.sourceforge.net/*checkout*/boost/boost/more/getting_started...
NOTE: if you simply follow this link instead of downloading it, your browser will probably display something garbled because the webserver is an old version of Apache that can't handle utf-8. Download the file to your disk instead (starting at http://boost.cvs.sourceforge.net/boost/boost/more/getting_started.html?view=... might be easier) and then view the file.
Note also: place the file in context in the more/ directory of a Boost distribution, or you won't get the stylesheet and the links won't work. Within a couple of hours, the new version of this page will be available in context at http://boost-consulting.com/boost/more/getting_started.html It might be easier to wait for that to become available. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Hi Dave, On 11/20/06, David Abrahams <dave@boost-consulting.com> wrote:
David Abrahams <dave@boost-consulting.com> writes:
Within a couple of hours, the new version of this page will be available in context at
http://boost-consulting.com/boost/more/getting_started.html
It might be easier to wait for that to become available.
Great job! This looks very good and easy on the eyes. However, will the .qbk sources be made available? I'd like to add a few things on the Windows MSVC build for 1.34 which you may have missed. There will be issues like with just `using msvc ;' in the user-config.jam file and other small details (like the compiler warnings that will be produced and should be ignored, etc.). I also like copy-editing documentation (had done this in high school and was pretty much having fun -- a hobby of course, which I want to be able to put into good use somday) and have a few things I'd like to point out -- some unintended grammatical and typographical errors in a few places -- and be able to change on my local copy before submitting a patch to you. Again, thanks and great job on the new getting started page! -- Dean Michael C. Berris C++ Software Architect Orange and Bronze Software Labs, Ltd. Co. web: http://software.orangeandbronze.com/ email: dean@orangeandbronze.com mobile: +63 928 7291459 phone: +63 2 8943415 other: +1 408 4049532 blogs: http://mikhailberis.blogspot.com http://3w-agility.blogspot.com http://cplusplus-soup.blogspot.com
"Dean Michael Berris" <mikhailberis@gmail.com> writes:
Hi Dave,
On 11/20/06, David Abrahams <dave@boost-consulting.com> wrote:
David Abrahams <dave@boost-consulting.com> writes:
Within a couple of hours, the new version of this page will be available in context at
http://boost-consulting.com/boost/more/getting_started.html
It might be easier to wait for that to become available.
Great job! This looks very good and easy on the eyes.
However, will the .qbk sources be made available?
It's not .qbk -- see the bottom of the page. http://boost-consulting.com/boost/more/getting_started.html is generated from http://boost-consulting.com/boost/more/getting_started.rst
I'd like to add a few things on the Windows MSVC build for 1.34 which you may have missed. There will be issues like with just `using msvc ;' in the user-config.jam file
It's not needed for getting started. The --toolset=msvc option handles that for you.
and other small details (like the compiler warnings that will be produced and should be ignored, etc.).
That might be useful, thanks.
I also like copy-editing documentation (had done this in high school and was pretty much having fun -- a hobby of course, which I want to be able to put into good use somday) and have a few things I'd like to point out -- some unintended grammatical and typographical errors in a few places -- and be able to change on my local copy before submitting a patch to you.
Looking forward to it.
Again, thanks and great job on the new getting started page!
:) -- Dave Abrahams Boost Consulting www.boost-consulting.com
On 11/20/06, David Abrahams <dave@boost-consulting.com> wrote:
"Dean Michael Berris" <mikhailberis@gmail.com> writes:
Great job! This looks very good and easy on the eyes.
However, will the .qbk sources be made available?
It's not .qbk -- see the bottom of the page.
http://boost-consulting.com/boost/more/getting_started.html
is generated from
Oh, my bad. I thought since it was a boost document, that it was written with Quickbook. :D
I'd like to add a few things on the Windows MSVC build for 1.34 which you may have missed. There will be issues like with just `using msvc ;' in the user-config.jam file
It's not needed for getting started. The --toolset=msvc option handles that for you.
This makes sense, for building just boost right? I seem to confuse configuring and using Boost.Build with building the boost distribution.
and other small details (like the compiler warnings that will be produced and should be ignored, etc.).
That might be useful, thanks.
No problem. :)
I also like copy-editing documentation (had done this in high school and was pretty much having fun -- a hobby of course, which I want to be able to put into good use somday) and have a few things I'd like to point out -- some unintended grammatical and typographical errors in a few places -- and be able to change on my local copy before submitting a patch to you.
Looking forward to it.
Now that I know it's rst, I'll try to give it a go soon as I can. :) -- Dean Michael C. Berris C++ Software Architect Orange and Bronze Software Labs, Ltd. Co. web: http://software.orangeandbronze.com/ email: dean@orangeandbronze.com mobile: +63 928 7291459 phone: +63 2 8943415 other: +1 408 4049532 blogs: http://mikhailberis.blogspot.com http://3w-agility.blogspot.com http://cplusplus-soup.blogspot.com
"Dean Michael Berris" <mikhailberis@gmail.com> writes:
On 11/20/06, David Abrahams <dave@boost-consulting.com> wrote:
"Dean Michael Berris" <mikhailberis@gmail.com> writes:
I'd like to add a few things on the Windows MSVC build for 1.34 which you may have missed. There will be issues like with just `using msvc ;' in the user-config.jam file
It's not needed for getting started. The --toolset=msvc option handles that for you.
This makes sense, for building just boost right? I seem to confuse configuring and using Boost.Build with building the boost distribution.
For better or worse, most of our users have other build systems and only need to use Boost.Build to build Boost binaries. -- Dave Abrahams Boost Consulting www.boost-consulting.com
| -----Original Message----- | From: boost-bounces@lists.boost.org | [mailto:boost-bounces@lists.boost.org] On Behalf Of Dean | Michael Berris | Sent: 20 November 2006 08:30 | To: boost@lists.boost.org | Subject: Re: [boost] New getting started guide | | Great job! This looks very good and easy on the eyes. Looks very good. I noted an unimportant but unintended display (Firefox 2.0) Most Windows compilers and linkers have so called “auto-linking support,†which is ---------------------------------------------------^_______________________^ Do you also need a total newbie to report back when trying it out? Or have you been there and done that already? Thanks Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
"Paul A Bristow" <pbristow@hetp.u-net.com> writes:
| -----Original Message----- | From: boost-bounces@lists.boost.org | [mailto:boost-bounces@lists.boost.org] On Behalf Of Dean | Michael Berris | Sent: 20 November 2006 08:30 | To: boost@lists.boost.org | Subject: Re: [boost] New getting started guide | | Great job! This looks very good and easy on the eyes.
Looks very good.
I noted an unimportant but unintended display (Firefox 2.0)
Most Windows compilers and linkers have so called “auto-linking support,†which is
---------------------------------------------------^_______________________^
That shouldn't be happening if you view from a unicode-capable server, as I tried to explain in foregoing messages. Did you look at http://boost-consulting.com/boost/more/getting_started.html? Working for me with FireFox 1.5.
Do you also need a total newbie to report back when trying it out?
Absolutely. I need several! I guess I should post about this on the Boost-User's list.
Or have you been there and done that already?
Not yet. -- Dave Abrahams Boost Consulting www.boost-consulting.com
| -----Original Message----- | From: boost-bounces@lists.boost.org | [mailto:boost-bounces@lists.boost.org] On Behalf Of David Abrahams | Sent: 20 November 2006 20:20 | To: boost@lists.boost.org | Subject: Re: [boost] New getting started guide | | > Looks very good. | > | > I noted an unimportant but unintended display (Firefox 2.0) | > | > Most Windows compilers and linkers have so called | “auto-linking support,†which is | > | > | ---------------------------------------------------^_________ | ______________^ | | That shouldn't be happening if you view from a unicode-capable server, | as I tried to explain in foregoing messages. Did you look at | | http://boost-consulting.com/boost/more/getting_started.html? You are right - works OK from here using Firefox 2.0. Sorry I didn't read the message carefully enough. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
On 11/20/06, David Abrahams <dave@boost-consulting.com> wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> writes:
Do you also need a total newbie to report back when trying it out?
Absolutely. I need several!
I tried to build Boost 1.33.1 and the example program with gcc 4.1.2 in kubuntu 6.10. It worked! :-) Well, I got some warnings and the final "Not all Boost libraries built properly." When I make again, I get: ------------------------------------------------------------ ./tools/build/jam_src/bin.linuxx86/bjam -sPYTHON_ROOT=/usr -sPYTHON_VERSION=2.4 -sTOOLS=gcc Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (and if you don't know what ICU is then you probably don't need it). ...found 10626 targets... ...updating 24 targets... gcc-C++-action bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o set -e "g++" -c -Wall -ftemplate-depth-255 -g -O0 -fno-inline -I"bin/boost/libs/iostreams/build" -I"/home/martin/boost_1_33_1" -I "/home/martin/boost_1_33_1" -o "bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o" "/home/martin/boost_1_33_1/libs/iostreams/build/../src/bzip2.cpp" "/usr/bin/objcopy" --set-section-flags .debug_str=contents,debug "bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o" ...failed gcc-C++-action bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o... gcc-C++-action bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/zlib.o [..] ------------------------------------------------------------ I have no idea what this is all about, but I got to compile, link and run the example so... :-) I had a little problem with the libraries: I installed them in /usr/local/lib (deafult location, isn't it?), but the system didn't find them at runtime. I had to append /usr/local/lib to /etc/ld.so.conf, and then run ldconfig. I decided to do so after reading: http://www.dwheeler.com/program-library/Program-Library-HOWTO/x36.html Regards, Martin
"Martin Knoblauch Revuelta" <mkrevuelta@gmail.com> writes:
I tried to build Boost 1.33.1 and the example program with gcc 4.1.2 in kubuntu 6.10.
It worked! :-)
Well, I got some warnings and the final "Not all Boost libraries built properly."
Sounds like it didn't work :(
When I make again, I get:
------------------------------------------------------------ ./tools/build/jam_src/bin.linuxx86/bjam -sPYTHON_ROOT=/usr -sPYTHON_VERSION=2.4 -sTOOLS=gcc
Okay, the first thing you need to know is that the version of Boost you're working with (and in particular, the version of Boost.Build used by the configure/make scripts) is out-of-date with respect to the instructions. Please try again with the RC_1_34_0 branch from Boost CVS.
Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (and if you don't know what ICU is then you probably don't need it). ...found 10626 targets... ...updating 24 targets...
OK so far.
gcc-C++-action bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o
set -e "g++" -c -Wall -ftemplate-depth-255 -g -O0 -fno-inline -I"bin/boost/libs/iostreams/build" -I"/home/martin/boost_1_33_1" -I "/home/martin/boost_1_33_1" -o "bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o" "/home/martin/boost_1_33_1/libs/iostreams/build/../src/bzip2.cpp" "/usr/bin/objcopy" --set-section-flags .debug_str=contents,debug "bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o"
...failed gcc-C++-action bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/bzip2.o... gcc-C++-action bin/boost/libs/iostreams/build/libboost_iostreams.a/gcc/debug/zlib.o
Err, there are no GCC error messages in there? OK, I'm seeing them on my own ubuntu machine. We need to resolve these issues with the iostreams library build.
I have no idea what this is all about, but I got to compile, link and run the example so... :-)
Well, that doesn't necessarily mean everything's OK. The first example doesn't depend on any of the libraries building correctly. The second example only depends on one of the libraries building successfully.
I had a little problem with the libraries: I installed them in /usr/local/lib (deafult location, isn't it?), but the system didn't find them at runtime.
I had to append /usr/local/lib to /etc/ld.so.conf, and then run ldconfig. I decided to do so after reading: http://www.dwheeler.com/program-library/Program-Library-HOWTO/x36.html
OK, I'll look into that and see if I can reproduce it. I don't actually have an ld.so.conf on my machine, so I might need to tell people to create that file if it doesn't already exist. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Within a couple of hours, the new version of this page will be available in context at
http://boost-consulting.com/boost/more/getting_started.html
It might be easier to wait for that to become available.
Great job! Thank you. Al though a question: The instructions do not tell how I would select the mingw compiler. Is this supposed to be automatic? What will happen if there is cygwin and mingw installed? I had to explicitly specify it in user-prefs.jam. Maybe I am overlooking something... Roland
Roland Schwarz <roland.schwarz@chello.at> writes:
David Abrahams wrote:
Within a couple of hours, the new version of this page will be available in context at
http://boost-consulting.com/boost/more/getting_started.html
It might be easier to wait for that to become available.
Great job! Thank you.
Al though a question: The instructions do not tell how I would select the mingw compiler.
Gee, I don't know how; I didn't see a mingw toolset when I prepared these instructions.
Is this supposed to be automatic?
Looking at gcc.jam I see that, yes, we now have automatic detection.
What will happen if there is cygwin and mingw installed?
I don't know. I think you can specify it explicitly with flavor=mingw on your command-line. That doesn't seem very satisfying; what is the value of flavor if you want to build with both? I think we should take this to the boost-build list.
I had to explicitly specify it in user-prefs.jam.
Maybe I am overlooking something...
I don't know. Why don't you try the instructions and see if they work for you? Where they fail, we'll have to fix something. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
... Why don't you try the instructions and see if they work for you? Where they fail, we'll have to fix something.
My findings so far: 1) bjam --v2 switch still necessary (I tried in the HEAD) 2) toolset=msvc builds e.g. boost_thread-vc-mt-gd-1_35.lib, i.e. no toolset version 3) toolset=gcc chooses the compiler which is closer in PATH. If you think this is reasonable enough, there is no need for action. I'd suggest to possibly mention it in the doc. I suspect msvc auto toolset choice is different, isn't it? This will choose the newer, not the "closer in PATH" one, does it? 4) For gcc I get a lot of warning: Unable to construct ./stage-unversioned messages upfront 5) It is possible to "invent" arbitrary toolset versions. e.g. it is possible to bjam --v2 --toolset=gcc-17.4 which results e.g. in boost_thread-gcc174-mt-d-1_35.dll. Don't know if this is expected, In particular I don't know which compiler really is getting used here (I suspect again the closer one in PATH) 6) Something similar is possible with msvc, but it does not compile, instead it gives you a _lot_ of error messages. I'd expected a simple message that the toolset isn't available. Roland
Roland Schwarz wrote:
David Abrahams wrote:
... Why don't you try the instructions and see if they work for you? Where they fail, we'll have to fix something.
My findings so far:
1) bjam --v2 switch still necessary (I tried in the HEAD)
In the RC branch that is not the case. We need to keep the BBv1 available in HEAD so that we can do comparisons between them. Although I guess we could add a "--v1" in HEAD, but perhaps it's not worth the effort.
2) toolset=msvc builds e.g. boost_thread-vc-mt-gd-1_35.lib, i.e. no toolset version
Which follows what BBv1 does. But maybe that's not a good thing seing as one was very unlikely to use an unversioned toolset.
3) toolset=gcc chooses the compiler which is closer in PATH. If you think this is reasonable enough, there is no need for action. I'd suggest to possibly mention it in the doc. I suspect msvc auto toolset choice is different, isn't it? This will choose the newer, not the "closer in PATH" one, does it?
I think we need to make this consistent across toolsets. AFAIR we've always preferred using the most recent toolset version.
4) For gcc I get a lot of warning: Unable to construct ./stage-unversioned messages upfront
Don't know what those are about.
5) It is possible to "invent" arbitrary toolset versions. e.g. it is possible to bjam --v2 --toolset=gcc-17.4 which results e.g. in boost_thread-gcc174-mt-d-1_35.dll. Don't know if this is expected, In particular I don't know which compiler really is getting used here (I suspect again the closer one in PATH)
Except for the auto-detected toolsets the version is entirely up to the user. This is true in both the command line and in the user-config.jam. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo
Rene Rivera <grafikrobot@gmail.com> writes:
2) toolset=msvc builds e.g. boost_thread-vc-mt-gd-1_35.lib, i.e. no toolset version
Which follows what BBv1 does. But maybe that's not a good thing seing as one was very unlikely to use an unversioned toolset.
It's especially bad as it breaks auto-linking.
3) toolset=gcc chooses the compiler which is closer in PATH. If you think this is reasonable enough, there is no need for action. I'd suggest to possibly mention it in the doc. I suspect msvc auto toolset choice is different, isn't it? This will choose the newer, not the "closer in PATH" one, does it?
I think we need to make this consistent across toolsets. AFAIR we've always preferred using the most recent toolset version.
I think the difference is that on *nix, it's very common to have a "system compiler" that is not as new as the newest compiler installed. For example, "gcc" might be version 3.4 and to get gcc-4.0.2 you need to write gcc-4. On Windows there's no notion of a "system compiler."
-- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-- Dave Abrahams Boost Consulting www.boost-consulting.com
On 11/20/06, Roland Schwarz <roland.schwarz@chello.at> wrote:
Al though a question: The instructions do not tell how I would select the mingw compiler. Is this supposed to be automatic? What will happen if there is cygwin and mingw installed?
Hi all, I just did a build of some libraries I needed off the cvs and used the new guide without having read this thread. Like Roland I use mingw. I was slightly confused that there was no mingw toolset mentioned any more and thought that maybe just passing gcc as toolset will do. However as it turns out I need to pass 'gcc-mingw' as toolset and I have to use the MSYS commandline to get rid of the warnings about 'unable to construct ./stage-unversioned'. Possibly auto detection of the gcc compiler doesn't work because of missing PATH environment parameters on my end. Maybe it works inside MSYS I haven't tried that after gcc-mingw did the job. I would like to see an example in the guide about how to specify build variants. This was mentioned in the old guide but was forgotten in the new one. The ABI tag 'g' is mentioned in the guide but it is not explained how to build such a variant of a library? I'm trying to figure this one out right now as I need it. I first did a staged build and then I did an install with the same options. I already had an install of the header files sitting in my prefix directory so that only the new libraries and a few updated headers needed to be copied over. For this operation bjam used up all my memory and then the os started swapping on the harddisk slowing the whole thing down even more and it didn't tell me what was going on so that I feared that it went into an infinite loop. I was glad once it was done. I just noticed bjam --help-all behaves in a similar way. Kevin
Dave, these are good, I like them :-) The main thing I noticed is that you give the msvc toolset name as simply "msvc", but if you build with bjam toolset=msvc then the libraries won't have the msvc version number in them and auto-linking won't work :-( Maybe lable the toolset as "msvc-x.y" and then define valid values for x and y in the text? John.
"John Maddock" <john@johnmaddock.co.uk> writes:
Dave, these are good, I like them :-)
The main thing I noticed is that you give the msvc toolset name as simply "msvc", but if you build with
bjam toolset=msvc
then the libraries won't have the msvc version number in them and auto-linking won't work :-(
Are you sure? If so, we should fix that. The toolset already has code to detect the version being used. Maybe this would assuage some of Volodya's concern about a toolset twice, once with and once without a version number.
Maybe lable the toolset as "msvc-x.y" and then define valid values for x and y in the text?
I'd rather make it "just work" than complicate the instructions. I do say that you can add an explicit version number if you choose to, but obviously that ain't enough. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
"John Maddock" <john@johnmaddock.co.uk> writes:
then the libraries won't have the msvc version number in them and auto-linking won't work :-(
Are you sure?
I can confirm that. toolset=msvc chooses the newest compiler, but has only tag VC, instead of VC80 in my case. Roland
On 11/19/06 6:02 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated.
[Also at: <http://boost.cvs.sourceforge.net/*checkout*/boost/boost/more/getting_starte d.html> (via <http://boost.cvs.sourceforge.net/boost/boost/more/getting_started.html?view =log>) or <http://boost-consulting.com/boost/more/getting_started.html>.]
I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst
There should be a section on going without pre-made binaries. This should mention the location of the mandatory source files ("$BOOST_ROOT/libs/*/src/*.cpp" for now) and that they can be arbitrarily incorporated as needed, except for the ones that have a "main" function. At most one file with a "main" can be added (for obvious reasons), and none of them should be added if the user supplies a "main" or is making a library. Of course, mention which files this applies to. (I think there's only 3 files so far, all in Boost.Test.) Potential reasons for this: * Environment doesn't support Boost.Build/Jam * Administrator-imposed restrictions blocking successful Boost-Builds * Want IDE to have 100%-control over building process * Especially with unusual settings * Especially if settings differ per project * Using Boost from CVS (forces continual rebuilding of pre-made libraries) The sentence starting section 4, "If you want to use any of the separately-compiled Boost libraries, you'll need to get a hold of library binaries," would need to be revised. -- Daryle Walker Mac, Internet, and Video Game Junkie darylew AT hotmail DOT com
Daryle Walker <darylew@hotmail.com> writes:
On 11/19/06 6:02 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated.
[Also at: <http://boost.cvs.sourceforge.net/*checkout*/boost/boost/more/getting_starte d.html> (via <http://boost.cvs.sourceforge.net/boost/boost/more/getting_started.html?view =log>) or <http://boost-consulting.com/boost/more/getting_started.html>.]
I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst
There should be a section on going without pre-made binaries. This should mention the location of the mandatory source files ("$BOOST_ROOT/libs/*/src/*.cpp" for now) and that they can be arbitrarily incorporated as needed, except for the ones that have a "main" function.
I don't believe that's true, though. Certainly I wouldn't guarantee it for Boost.Python; you'd have to know a lot of details about how to configure the build. I'm not going to make guarantees that users can do something that they can't in fact do or anything that we don't test. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On 11/22/06 11:15 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
There should be a section on going without pre-made binaries. This should mention the location of the mandatory source files ("$BOOST_ROOT/libs/*/src/*.cpp" for now) and that they can be arbitrarily incorporated as needed, except for the ones that have a "main" function.
I don't believe that's true, though. Certainly I wouldn't guarantee it for Boost.Python; you'd have to know a lot of details about how to configure the build. I'm not going to make guarantees that users can do something that they can't in fact do or anything that we don't test.
Should that be considered a bug? [Hmm... looking around Boost.Python for the first time at <http://www.boost.org>.] The example at <http://www.boost.org/libs/python/doc/tutorial/doc/html/python/hello.html> uses bjam and suggests that it's the preferred way. It links to another page at <http://www.boost.org/libs/python/doc/building.html> with alternate methods with either use Boost.Build or a pre-canned file for Visual Studio IDE users. I don't see directions to set up Boost.Python manually, when none of the given methods are possible. Maybe manual directions need to be added to the general and Boost.Python-specific getting-started pages. -- Daryle Walker Mac, Internet, and Video Game Junkie darylew AT hotmail DOT com
Daryle Walker <darylew@hotmail.com> writes:
On 11/22/06 11:15 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
There should be a section on going without pre-made binaries. This should mention the location of the mandatory source files ("$BOOST_ROOT/libs/*/src/*.cpp" for now) and that they can be arbitrarily incorporated as needed, except for the ones that have a "main" function.
I don't believe that's true, though. Certainly I wouldn't guarantee it for Boost.Python; you'd have to know a lot of details about how to configure the build. I'm not going to make guarantees that users can do something that they can't in fact do or anything that we don't test.
Should that be considered a bug?
Not unless we decide to support it, and nobody has made that decision.
[Hmm... looking around Boost.Python for the first time at <http://www.boost.org>.]
The example at <http://www.boost.org/libs/python/doc/tutorial/doc/html/python/hello.html> uses bjam and suggests that it's the preferred way. It links to another page at <http://www.boost.org/libs/python/doc/building.html> with alternate methods with either use Boost.Build or a pre-canned file for Visual Studio IDE users.
Yeah, which file is probably seriously outdated by now and should be taken down. I need to check, but I don't think its maintainer has been keeping it up.
I don't see directions to set up Boost.Python manually, when none of the given methods are possible.
Right.
Maybe manual directions need to be added to the general and Boost.Python-specific getting-started pages.
I'm not ready to support that method, sorry. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On 11/25/06 5:47 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
Daryle Walker <darylew@hotmail.com> writes:
On 11/22/06 11:15 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
There should be a section on going without pre-made binaries. This should mention the location of the mandatory source files ("$BOOST_ROOT/libs/*/src/*.cpp" for now) and that they can be arbitrarily incorporated as needed, except for the ones that have a "main" function.
I don't believe that's true, though. Certainly I wouldn't guarantee it for Boost.Python; you'd have to know a lot of details about how to configure the build. I'm not going to make guarantees that users can do something that they can't in fact do or anything that we don't test.
Should that be considered a bug?
Not unless we decide to support it, and nobody has made that decision.
I don't think Boost, are any part of it, should _require_ an install procedure. It should be possible for any user to just take the actual header and source files and use any build system s/he has. [SNIP]
I don't see directions to set up Boost.Python manually, when none of the given methods are possible.
Right.
Maybe manual directions need to be added to the general and Boost.Python-specific getting-started pages.
I'm not ready to support that method, sorry.
For the Python-specific directions or the general ones (or both)? If just the Python-specific ones, the general page could have a note about the situation with Boost.Python. For Boost.Python, what does happen if the user has a setup incompatible with the given directions? Give up? Guess what to do? Petition for help on our mailing lists? -- Daryle Walker Mac, Internet, and Video Game Junkie darylew AT hotmail DOT com
Daryle Walker <darylew@hotmail.com> writes:
On 11/25/06 5:47 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
Daryle Walker <darylew@hotmail.com> writes:
On 11/22/06 11:15 PM, "David Abrahams" <dave@boost-consulting.com> wrote:
There should be a section on going without pre-made binaries. This should mention the location of the mandatory source files ("$BOOST_ROOT/libs/*/src/*.cpp" for now) and that they can be arbitrarily incorporated as needed, except for the ones that have a "main" function.
I don't believe that's true, though. Certainly I wouldn't guarantee it for Boost.Python; you'd have to know a lot of details about how to configure the build. I'm not going to make guarantees that users can do something that they can't in fact do or anything that we don't test.
Should that be considered a bug?
Not unless we decide to support it, and nobody has made that decision.
I don't think Boost, are any part of it, should _require_ an install procedure. It should be possible for any user to just take the actual header and source files and use any build system s/he has.
Great, you can work towards establishing that as a supported method for 1.35
Maybe manual directions need to be added to the general and Boost.Python-specific getting-started pages.
I'm not ready to support that method, sorry.
For the Python-specific directions or the general ones (or both)? If just the Python-specific ones, the general page could have a note about the situation with Boost.Python.
Neither, because I can't stand behind them working.
For Boost.Python, what does happen if the user has a setup incompatible with the given directions? Give up? Guess what to do? Petition for help on our mailing lists?
Any of those could be appropriate. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated.
I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst
Some quick comments: Usage of "boost_1_34_0" (everywhere): - I don't know - is this something that should change in each Boost release in the getting started guide? I understand that something like this is perhaps easier to understand that e.g. "<boost root>" or $BOOST_ROOT, but it'll lead to some extra maintenance for you(?). References: - What about adding some explicit references to e.g. the Boost.Build, Boost.Jam manuals and perhaps also the Boost.Build wiki somewhere near the start of the document? "*nix (....)" usage in headers: - I'm not too fond of the usage of "*nix", especially not in headers - why not "Unix variants" or similar. Just my personal opinion, though. The structure of a Boost distribution(2): - "index.html ... a copy of www.boost.org"; sounds like it contains, well, a copy of the site (nagging, yes, I know). Building a simple Boost program (3): - "Nearly all Boost libraries are header-only" - ten that are not header-only are listed (excluding DateTime). Maybe "Most Boost libraries" would be more appropriate? - Typo (3.2) - "From your computer's Start menu, select if you are a Visual Studio 2005 user, select ..." (select ... select). - Typo(3.2) - the command prompt in the MS examples are "C:PROMPT>" instead of "C:\PROMPT>" Build directory (4.4.3 onwards): - Is the "--build-dir" option actually respected? - In the root Jamfile.v2 (and in v1) it is called "--builddir" Select a prefix directory (4.4.6): - Maybe it's just me, but "prefix" doesn't feel like a common word for selecting the install directory. Why not have "destination" or "install" directory in the header, and explain that this is selected using the "--prefix" argument? - What about --includedir and --libdir, should they also be included here, or just referenced? Toolset tags (5.1.1, 5.3, and more ...): - I believe that the generated toolset tag for e.g. msvc V.1 is actually "vc71" ... Library paths (5.1.1, 5.2): - Perhaps give the same information and hints for using /LIBPATH: (msvc) as for -L (gcc) when not auto-linking. Staging (4.4.4-5): - There's some duplication between the two paragrahs (stage target explanation) / Johan
"Johan Nilsson" <r.johan.nilsson@gmail.com> writes:
David Abrahams wrote:
I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated.
I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst
Some quick comments:
Usage of "boost_1_34_0" (everywhere):
- I don't know - is this something that should change in each Boost release in the getting started guide? I understand that something like this is perhaps easier to understand that e.g. "<boost root>" or $BOOST_ROOT, but it'll lead to some extra maintenance for you(?).
Don't worry, there's a single substitution reference in the source for that file. Not much to maintain.
References:
- What about adding some explicit references to e.g. the Boost.Build, Boost.Jam manuals and perhaps also the Boost.Build wiki somewhere near the start of the document?
There already are explicit references to everything but the wiki. If you want to suggest a patch, I'll gladly consider specific changes. However, I don't want to get the user involved with any of that stuff near the beginning of the document because most likely she doesn't need it in order to get started.
"*nix (....)" usage in headers:
Headers?
- I'm not too fond of the usage of "*nix", especially not in headers - why not "Unix variants" or similar. Just my personal opinion, though.
Just going with someone else's suggestion who was unhappy with specific mentions of unix. I'm open to whatever people decide is most comfortable.
The structure of a Boost distribution(2):
- "index.html ... a copy of www.boost.org"; sounds like it contains, well, a copy of the site (nagging, yes, I know).
Okay, that could be more accurate, but do you have a specific suggestion?
Building a simple Boost program (3):
- "Nearly all Boost libraries are header-only" - ten that are not header-only are listed (excluding DateTime). Maybe "Most Boost libraries" would be more appropriate?
Why?
- Typo (3.2) - "From your computer's Start menu, select if you are a Visual Studio 2005 user, select ..." (select ... select).
Thanks.
- Typo(3.2) - the command prompt in the MS examples are "C:PROMPT>" instead of "C:\PROMPT>"
Thanks.
Build directory (4.4.3 onwards):
- Is the "--build-dir" option actually respected?
AFAIK. Why?
- In the root Jamfile.v2 (and in v1) it is called "--builddir"
What does Jamfile.v2 have to do with it? It's provided by the build system, not the Jamfiles.
Select a prefix directory (4.4.6):
- Maybe it's just me, but "prefix" doesn't feel like a common word for selecting the install directory.
Maybe it's just you. That's the standard *nix terminology.
Why not have "destination" or "install" directory in the header, and explain that this is selected using the "--prefix" argument?
I'm not sure it could be as clear.
- What about --includedir and --libdir, should they also be included here, or just referenced?
Neither. I don't want to tell people how to customize everything, just how to get over the hump of getting started. They'll get those options from the configure script when they do ./configure --help.
Toolset tags (5.1.1, 5.3, and more ...):
- I believe that the generated toolset tag for e.g. msvc V.1 is actually "vc71" ...
msvc V.1 ?
Library paths (5.1.1, 5.2):
- Perhaps give the same information and hints for using /LIBPATH: (msvc) as for -L (gcc) when not auto-linking.
Probably a good idea.
Staging (4.4.4-5):
- There's some duplication between the two paragrahs (stage target explanation)
Thanks! -- Dave Abrahams Boost Consulting www.boost-consulting.com
-----Original Message----- From: boost-bounces@lists.boost.org on behalf of David Abrahams [begin quote]
- I'm not too fond of the usage of "*nix", especially not in headers - why not "Unix variants" or similar. Just my personal opinion, though.
Just going with someone else's suggestion who was unhappy with specific mentions of unix. I'm open to whatever people decide is most comfortable. [end quote] I've been asked if I'm talking about a basketball team when I talk about *nix! So +1 for Unix variant from me. By the way, good document. I think it would be very useful to have a section (or separate document?) on how to incorporate boost into your project's build / source control. Currently I use "vendor branches" as described in the subversion book. I'm not sure of a better way myself :) I think this question came up elsewhere last week as well. Sohail
David Abrahams wrote:
"Johan Nilsson" <r.johan.nilsson@gmail.com> writes:
David Abrahams wrote:
I've got a first draft of the new getting started guide ready (enclosed). Comments would be appreciated.
I plan to factor it out into separate documents, e.g. one just for *nix, one just for Visual Studio, etc., which should help make it more coherent... but I need to do a small amount of tool writing before I can accomplish that without duplicating information. The source file is checked in at more/getting_started.rst
[snip]
References:
- What about adding some explicit references to e.g. the Boost.Build, Boost.Jam manuals and perhaps also the Boost.Build wiki somewhere near the start of the document?
There already are explicit references to everything but the wiki.
Do you refer to the hyperlinks under 4.4? I didn't consider hyperlinks being explicit references, hence my wording.
If you want to suggest a patch, I'll gladly consider specific changes. However, I don't want to get the user involved with any of that stuff near the beginning of the document because most likely she doesn't need it in order to get started.
Ok. How about a "References", or "Where to go for further help" section at the end of the document: Boost.Build reference manual: (hyperlink) Boost.Jam reference manual: (hyperlink) Boost.Build Wiki: (hyperlink) Boost User's mailing list: (hyperlink) (not a patch, I know)
"*nix (....)" usage in headers:
Headers?
Pardon my English. I guess I mean "headings" or perhaps "section headings"?
- I'm not too fond of the usage of "*nix", especially not in headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~headings.
- why not "Unix variants" or similar. Just my personal opinion, though.
Just going with someone else's suggestion who was unhappy with specific mentions of unix. I'm open to whatever people decide is most comfortable.
Unix variants? Unix-type systems? Unix-compatible systems? The first is my own preference, at least until I've seen something better. Perhaps adding an explanation near the beginning of the document would be a good idea: In this document, the term "Unix variants" is used as a collective reference to different *nix platforms, including ...
The structure of a Boost distribution(2):
- "index.html ... a copy of www.boost.org"; sounds like it contains, well, a copy of the site (nagging, yes, I know).
Okay, that could be more accurate, but do you have a specific suggestion?
Nothing really good, but either "a copy from www.boost.org", or "a copy of www.boost.org/index.html" would at least be more accurate. Actually (just tried this), www.boost.org/index.html renders a 404 error (www.boost.org/index.htm works).
Building a simple Boost program (3):
- "Nearly all Boost libraries are header-only" - ten that are not header-only are listed (excluding DateTime). Maybe "Most Boost libraries" would be more appropriate?
Why?
Because, at least as a non-native English speaker, I find that a ratio of some 55ish header-only out of some 66ish in total sounds more like "most of" than "nearly all" (the number 66 came from the number of directories under <boost root>/libs). Whatever - I don't feel too strongly about this. [snip]
Build directory (4.4.3 onwards):
- Is the "--build-dir" option actually respected?
AFAIK. Why?
Ok, just tested it and works fine. See next point though, which is the reason why I was wondering.
- In the root Jamfile.v2 (and in v1) it is called "--builddir"
What does Jamfile.v2 have to do with it? It's provided by the build system, not the Jamfiles.
Try to invoke bjam --help from the boost root and check the listed options. The help is (at least partially AFAIK) extracted from the root Jamfile.v2.
Select a prefix directory (4.4.6):
- Maybe it's just me, but "prefix" doesn't feel like a common word for selecting the install directory.
Maybe it's just you. That's the standard *nix terminology.
Perhaps, but Boost isn't meant for *nix users only.
Why not have "destination" or "install" directory in the header, and explain that this is selected using the "--prefix" argument?
I'm not sure it could be as clear.
- What about --includedir and --libdir, should they also be included here, or just referenced?
Neither. I don't want to tell people how to customize everything, just how to get over the hump of getting started.
I understand that.
They'll get those options from the configure script when they do ./configure --help.
So, under Windows, I'll do ./configure --help? (sorry, but you get the point). Why not add a reference at the end of the section, e.g.: For a description of all available installation options, please see <link provided here>. or For a description of all available installation options, invoke "bjam --help" from <insert boost root directory here>.
Toolset tags (5.1.1, 5.3, and more ...):
- I believe that the generated toolset tag for e.g. msvc V.1 is actually "vc71" ...
msvc V.1 ?
Typo, should be "msvc 7.1" (of course). [snip rest] Regards / Johan
"Johan Nilsson" <r.johan.nilsson@gmail.com> writes:
Ok. How about a "References", or "Where to go for further help" section at the end of the document:
Boost.Build reference manual: (hyperlink) Boost.Jam reference manual: (hyperlink) Boost.Build Wiki: (hyperlink) Boost User's mailing list: (hyperlink)
Done.
"*nix (....)" usage in headers:
Headers?
Pardon my English. I guess I mean "headings" or perhaps "section headings"?
- I'm not too fond of the usage of "*nix", especially not in headers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~headings.
- why not "Unix variants" or similar. Just my personal opinion, though.
Just going with someone else's suggestion who was unhappy with specific mentions of unix. I'm open to whatever people decide is most comfortable.
Unix variants? Unix-type systems? Unix-compatible systems?
The first is my own preference, at least until I've seen something better. Perhaps adding an explanation near the beginning of the document would be a good idea:
The problem with "Unix variants" is that it makes all kinds of things incredibly awkward to write and read. For example, how do you say *nix users *nix binaries ?? users of unix variants binaries for unix variants ??
In this document, the term "Unix variants" is used as a collective reference to different *nix platforms, including ...
I added just such an explanation of *nix.
The structure of a Boost distribution(2):
- "index.html ... a copy of www.boost.org"; sounds like it contains, well, a copy of the site (nagging, yes, I know).
Okay, that could be more accurate, but do you have a specific suggestion?
Nothing really good, but either "a copy from www.boost.org", or "a copy of www.boost.org/index.html" would at least be more accurate.
"A copy of www.boost.org starts here."
Actually (just tried this), www.boost.org/index.html renders a 404 error (www.boost.org/index.htm works).
Fixed.
Building a simple Boost program (3):
- "Nearly all Boost libraries are header-only" - ten that are not header-only are listed (excluding DateTime). Maybe "Most Boost libraries" would be more appropriate?
Why?
Because, at least as a non-native English speaker, I find that a ratio of some 55ish header-only out of some 66ish in total sounds more like "most of" than "nearly all" (the number 66 came from the number of directories under <boost root>/libs). Whatever - I don't feel too strongly about this.
Fixed.
Select a prefix directory (4.4.6):
- Maybe it's just me, but "prefix" doesn't feel like a common word for selecting the install directory.
Maybe it's just you. That's the standard *nix terminology.
Perhaps, but Boost isn't meant for *nix users only.
That section was never supposed to be in the flow of the reading for non-*nix users.
Why not have "destination" or "install" directory in the header, and explain that this is selected using the "--prefix" argument?
I'm not sure it could be as clear.
- What about --includedir and --libdir, should they also be included here, or just referenced?
Neither. I don't want to tell people how to customize everything, just how to get over the hump of getting started.
I understand that.
They'll get those options from the configure script when they do ./configure --help.
So, under Windows, I'll do ./configure --help? (sorry, but you get the point).
Uh, no. The instructions for Windows users do not suggest the use of configure.
Why not add a reference at the end of the section, e.g.:
For a description of all available installation options, please see <link provided here>.
Sure, great. What will I link to?
or
For a description of all available installation options, invoke "bjam --help" from <insert boost root directory here>.
That's more useful; I'll add that.
Toolset tags (5.1.1, 5.3, and more ...):
- I believe that the generated toolset tag for e.g. msvc V.1 is actually "vc71" ...
msvc V.1 ?
Typo, should be "msvc 7.1" (of course).
OK, thanks. -- Dave Abrahams Boost Consulting www.boost-consulting.com
participants (12)
-
Andrew Schweitzer -
Daryle Walker -
David Abrahams -
Dean Michael Berris -
Johan Nilsson -
John Maddock -
Kevin Sopp -
Martin Knoblauch Revuelta -
Paul A Bristow -
Rene Rivera -
Roland Schwarz -
Sohail Somani