Getting started with Boost: what did you need to know?
I'm giving a talk about getting started with Boost (https://www.cmpevents.com/SDw6/a.asp?option=G&V=3&id=271893) and I thought it would be a good idea to solicit input from those who have recently gone through the process. What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated. Thanks, -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jan 30, 2006, at 11:17 AM, David Abrahams wrote:
What do you wish someone had explained to you?
It would be nice to update the installation documentation to point out that at least the latest distribution includes bjam, so one doesn't need to download it separately, and that the config script in at least the latest distribution will build bjam and create makefiles which will invoke the built bjam executable to build and install Boost. Regards, -Steve -------- Steve Byan <smb@egenera.com> Software Architect Egenera, Inc. 165 Forest Street Marlboro, MA 01752 (508) 858-3125
Dear Steve - Glad to hear you are doing this. After many hours, I am still trying to get started with Boost. I have been trying to use Boost serialization. I am working on a linux box. I have followed download and installation directions, rather carefully, I think. After trying unsuccessfully to compile and link my own "Hello, Serialization" program, I downloaded and tried the serialization demo. I have still not been able to link this. I get copious errors complaining of undefined references. A typical one is undefined reference to `boost::archive::basic_text_iprimitive<std::basic_istream<char, std::char_traits<char> > >::basic_text_iprimitive(std::basic_istream<char, std::char_traits<char> >&, bool)' I have found several people asking how to fix this problem on the Boost users' group, but have not been able to find instructions anywhere that would solve it. As things now stand, I can't tell whether a) My build is incorrect. b) I am failing to set some environment variable. c) I am failing to link some library or correctly set some compiler flag. Okay, I have whined long enough. What would be helpful would be a) Complete instructions for building Boost. (I worked from the getting started page. It was only after much hacking around that I found another page telling me I needed compiler_status and process_jam_log. b) Instructions on how to tell is your build is complete and correct. c) An example of how to compile and link the demo, either from the command line or via a make file. Hope this is helpful, Michael Shapiro On Monday 30 January 2006 11:57, Steve Byan wrote:
On Jan 30, 2006, at 11:17 AM, David Abrahams wrote:
What do you wish someone had explained to you?
It would be nice to update the installation documentation to point out that at least the latest distribution includes bjam, so one doesn't need to download it separately, and that the config script in at least the latest distribution will build bjam and create makefiles which will invoke the built bjam executable to build and install Boost.
Regards, -Steve -------- Steve Byan <smb@egenera.com> Software Architect Egenera, Inc. 165 Forest Street Marlboro, MA 01752 (508) 858-3125
_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users
Michael Shapiro <mshapiro@vbi.vt.edu> writes:
Dear Steve -
Glad to hear you are doing this.
Ahem. It's Dave. :)
After many hours, I am still trying to get started with Boost. I have been trying to use Boost serialization. I am working on a linux box. I have followed download and installation directions, rather carefully, I think. After trying unsuccessfully to compile and link my own "Hello, Serialization" program, I downloaded and tried the serialization demo. I have still not been able to link this. I get copious errors complaining of undefined references. A typical one is
undefined reference to `boost::archive::basic_text_iprimitive<std::basic_istream<char, std::char_traits<char> > >::basic_text_iprimitive(std::basic_istream<char, std::char_traits<char> >&, bool)'
I have found several people asking how to fix this problem on the Boost users' group, but have not been able to find instructions anywhere that would solve it.
As things now stand, I can't tell whether
a) My build is incorrect. b) I am failing to set some environment variable. c) I am failing to link some library or correctly set some compiler flag.
I'm pretty sure it's c: you're failing to link the Boost serialization library. But you should make a post about that whose subject starts with "[serialization]" so that the maintainer can help you with that problem.
Okay, I have whined long enough. What would be helpful would be a) Complete instructions for building Boost. (I worked from the getting started page.
In what way is that page incomplete?
It was only after much hacking around that I found another page telling me I needed compiler_status and process_jam_log.
You did? Which page, please? You certainly don't need either one of those in order to build Boost.
b) Instructions on how to tell is your build is complete and correct.
Hmm, good one. When bjam completes it will tell you whether there were errors. If there were no errors, you can assume it was complete and correct. Or did you have something else in mind?
c) An example of how to compile and link the demo, either from the command line or via a make file.
That, again, sounds like something specific to the serialization library. In other words, the serialization library author ought to improve his docs. So, add that to your message with "[serialization]" in the subject line.
Hope this is helpful,
Once you answer the questions I'm posing in response, I think it will be. Thanks for your time, Dave -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Monday 30 January 2006 17:37, David Abrahams wrote:
Michael Shapiro <mshapiro@vbi.vt.edu> writes:
Dear Steve -
Glad to hear you are doing this.
Ahem. It's Dave. :)
After many hours, I am still trying to get started with Boost. I have been trying to use Boost serialization. I am working on a linux box. I have followed download and installation directions, rather carefully, I think. After trying unsuccessfully to compile and link my own "Hello, Serialization" program, I downloaded and tried the serialization demo. I have still not been able to link this. I get copious errors complaining of undefined references. A typical one is
undefined reference to `boost::archive::basic_text_iprimitive<std::basic_istream<char, std::char_traits<char> >
::basic_text_iprimitive(std::basic_istream<char, std::char_traits<char> &, bool)'
I have found several people asking how to fix this problem on the Boost users' group, but have not been able to find instructions anywhere that would solve it.
As things now stand, I can't tell whether
a) My build is incorrect. b) I am failing to set some environment variable. c) I am failing to link some library or correctly set some compiler flag.
I'm pretty sure it's c: you're failing to link the Boost serialization library. But you should make a post about that whose subject starts with "[serialization]" so that the maintainer can help you with that problem.
Thanks. I will give that a try when I have a chance to get back to this.
Okay, I have whined long enough. What would be helpful would be a) Complete instructions for building Boost. (I worked from the getting started page.
In what way is that page incomplete?
This claim may be wrong. When I wrote it, I was under the impression that I needed compiler_status and process_jam_log (see below). However, it may not be wrong. If I ever get any of this to run, I'll know if there was something missing here.
It was only after much hacking around that I found another page telling me I needed compiler_status and process_jam_log.
You did? Which page, please? You certainly don't need either one of those in order to build Boost.
This is in boost_1_32_0/more/regression.html By then I was looking for ways to test the installation and sufficiently flummoxed to wonder if I needed these for the original build.
b) Instructions on how to tell is your build is complete and correct.
Hmm, good one. When bjam completes it will tell you whether there were errors. If there were no errors, you can assume it was complete and correct. Or did you have something else in mind?
I'm not sure what would work here. When bjam lists the number of targets found and then says it is making a smaller number of targets, it's unclear to the novice whether the targets that are being omitted should be omitted. I suppose a static test of this would be in the form of a check to see that all files are where they should be. I guess this is platform dependent and might be a pain to maintain. Perhaps a better idea would be a test suite that builds and runs a set of basic examples from each of the libraries and checks their results. This would have the advantages of a) discovering whether the basics work, thus b) exhonerating the installation and convicting me of my own ignorance if my examples don't work, and c) giving me the means to remedy my ignorance by looking at the examples embedded in the test suite.
c) An example of how to compile and link the demo, either from the command line or via a make file.
That, again, sounds like something specific to the serialization library. In other words, the serialization library author ought to improve his docs. So, add that to your message with "[serialization]" in the subject line.
Hope this is helpful,
Once you answer the questions I'm posing in response, I think it will be. Thanks for your time,
Dave
Michael Shapiro <mshapiro@vbi.vt.edu> writes:
On Monday 30 January 2006 17:37, David Abrahams wrote:
Michael Shapiro <mshapiro@vbi.vt.edu> writes:
Okay, I have whined long enough. What would be helpful would be a) Complete instructions for building Boost. (I worked from the getting started page.
In what way is that page incomplete?
This claim may be wrong. When I wrote it, I was under the impression that I needed compiler_status and process_jam_log (see below). However, it may not be wrong. If I ever get any of this to run, I'll know if there was something missing here.
:)
It was only after much hacking around that I found another page telling me I needed compiler_status and process_jam_log.
You did? Which page, please? You certainly don't need either one of those in order to build Boost.
This is in boost_1_32_0/more/regression.html By then I was looking for ways to test the installation and sufficiently flummoxed to wonder if I needed these for the original build.
b) Instructions on how to tell is your build is complete and correct.
Hmm, good one. When bjam completes it will tell you whether there were errors. If there were no errors, you can assume it was complete and correct. Or did you have something else in mind?
I'm not sure what would work here. When bjam lists the number of targets found and then says it is making a smaller number of targets, it's unclear to the novice whether the targets that are being omitted should be omitted.
Yeah, we had a long discussion about that, and some people came up with good ideas, but there was never a solid proposal that would work. I would appreciate it if someone could come up with one. http://lists.boost.org/Archives/boost/2005/05/87597.php Ultimately, the output of a tool used for the edit/build/debug cycle is probably not appropriate for the build-to-install user.
I suppose a static test of this would be in the form of a check to see that all files are where they should be. I guess this is platform dependent and might be a pain to maintain.
Yeah.
Perhaps a better idea would be a test suite that builds and runs a set of basic examples from each of the libraries and checks their results. This would have the advantages of a) discovering whether the basics work, thus b) exhonerating the installation and convicting me of my own ignorance if my examples don't work, and c) giving me the means to remedy my ignorance by looking at the examples embedded in the test suite.
We have a comprehensive test suite in the status/ subdirectory. If you do bjam test there, it will test everything. If you go to libs/<library>/test and issue the same command there, it will test just that library. Here's the problem: the libraries as built for testing are not 100% identical to those built for installation. They differ in location and in name, for reasons that are hard to explain -- this has to do again with the difference between edit/build/test and build-to-install. The upshot is that bjam will be testing different library files than the ones that result from your bjam install. It would be interesting to be able to have an option that runs tests with the libraries in their installed locations and using their installed names. I'm not sure how difficult that would be.
c) An example of how to compile and link the demo, either from the command line or via a make file.
That, again, sounds like something specific to the serialization library. In other words, the serialization library author ought to improve his docs. So, add that to your message with "[serialization]" in the subject line.
Thanks again. I really hope you take my advice about that, because otherwise your keen insight will be wasted. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Steve Byan <smb@egenera.com> writes:
On Jan 30, 2006, at 11:17 AM, David Abrahams wrote:
What do you wish someone had explained to you?
It would be nice to update the installation documentation to point out that at least the latest distribution includes bjam, so one doesn't need to download it separately,
If you mean the latest release of Boost, then it has always included the bjam sources, but has never included a bjam executable. I think it's pretty clear from the docs that the sources for bjam are part of the Boost release, isn't it? The need to build a tool just to be able to build boost was seen as anathema to many people (different programming cultures have different needs), so the Getting Started guide strongly encouraged downloading a prebuilt bjam executable. If you're talking about some distribution of Boost packaged for installation on, say, Debian or RedHat, then those are not prepared by the Boost developers and historically we have taken no responsibility for their contents. That actually *ought* to be made clear in our docs and we ought to coordinate with the maintainers of those distros to make sure there are appropriate instructions for their users on our website. I'll definitely mention that in my talk.
and that the config script in at least the latest distribution will build bjam and create makefiles which will invoke the built bjam executable to build and install Boost.
Doc patches are always welcome. My improvements will probably come in the form of an article. I'll certainly mention in my talk that there's a configure script for those who are comfortable with ./configure && make && make install Thanks for your feedback. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jan 30, 2006, at 5:31 PM, David Abrahams wrote:
Steve Byan <smb@egenera.com> writes:
On Jan 30, 2006, at 11:17 AM, David Abrahams wrote:
What do you wish someone had explained to you?
It would be nice to update the installation documentation to point out that at least the latest distribution includes bjam, so one doesn't need to download it separately,
If you mean the latest release of Boost, then it has always included the bjam sources, but has never included a bjam executable. I think it's pretty clear from the docs that the sources for bjam are part of the Boost release, isn't it?
Not to me :-)
The need to build a tool just to be able to build boost was seen as anathema to many people (different programming cultures have different needs), so the Getting Started guide strongly encouraged downloading a prebuilt bjam executable.
I didn't want to depend on a pre-built executable in my project, so I downloaded the source rather than a pre-built executable, built and installed bjam, and then discovered that it was already included in the Boost distribution and had a pre-packaged "build bjam" configure script, and moreover that the makefiles auto-generated by the configure script use the absolute path to the built bjam rather than the one in my path. This was a surprise to me; maybe I missed something in the Getting Started.
If you're talking about some distribution of Boost packaged for installation on, say, Debian or RedHat, then those are not prepared by the Boost developers and historically we have taken no responsibility for their contents.
No, no, I was just surprised that the bjam source was part of the Boost distribution and that the configure-generated makefile did not make use of any bjam in my path but instead hard-coded the path to the executable built out of the distribution.
That actually *ought* to be made clear in our docs and we ought to coordinate with the maintainers of those distros to make sure there are appropriate instructions for their users on our website. I'll definitely mention that in my talk.
and that the config script in at least the latest distribution will build bjam and create makefiles which will invoke the built bjam executable to build and install Boost.
Doc patches are always welcome. My improvements will probably come in the form of an article.
I'll look forward to it.
I'll certainly mention in my talk that there's a configure script for those who are comfortable with
./configure && make && make install
Thanks for your feedback.
Thank you for your work on Boost. Regards, -Steve -------- Steve Byan <smb@egenera.com> Software Architect Egenera, Inc. 165 Forest Street Marlboro, MA 01752 (508) 858-3125
If you mean the latest release of Boost, then it has always included the bjam sources, but has never included a bjam executable. I think it's pretty clear from the docs that the sources for bjam are part of the Boost release, isn't it? The need to build a tool just to be able to build boost was seen as anathema to many people (different programming cultures have different needs), so the Getting Started guide strongly encouraged downloading a prebuilt bjam executable.
A significant number of questions posted here is about linking errors and thus prebuilt boost libraries. If I am new to a library, I should exactly told what to do (click on this, click on that), and therefore made an article on www.codetools.com 'Building Boost libraries for Visual Studio' intended for the same audience as myself. In general I find the boost documentation not too bad, but as always it could better. Perhaps a good tip is to let a third person write the documentation, but this can be difficult since most people have regular jobs. Further on, I still haven't figured out, how to print these new boost book format... A prebuilt pdf or big html would be nice here... Wkr, me
gast128 <gast128@hotmail.com> writes:
A significant number of questions posted here is about linking errors and thus prebuilt boost libraries.
Yes.
If I am new to a library, I should exactly told what to do (click on this, click on that),
Unfortunately, "click click" style instructions tend to be very specific to one group of people. In the case of Visual Studio users, it's a very large group, and maybe we should make special accomodations. I can certainly make some mention of this in my talk. However, you must realize that it's extra effort for anyone doing the documentation.
and therefore made an article on www.codetools.com 'Building Boost libraries for Visual Studio' intended for the same audience as myself.
Nice! But it looks wrong at step 1. The bjam commands you show there do not generate batch files as you claim. They build the Boost libraries!
In general I find the boost documentation not too bad, but as always it could better. Perhaps a good tip is to let a third person write the documentation,
Hehehe. Good tip. We'd be happy to allow a third person write the docs (if that person can do a good job) -- the problem is finding competent third persons who are willing to do it!
but this can be difficult since most people have regular jobs.
Further on, I still haven't figured out, how to print these new boost book format... A prebuilt pdf or big html would be nice here...
Interesting. Doesn't help much with my talk; maybe you should post this to the boost-docs mailing list, where someone who can do something about it will respond. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Nice! But it looks wrong at step 1.
The bjam commands you show there do not generate batch files as you claim. They build the Boost libraries!
Yes you are right, I hope I did communicate it in that way. I was thinking myself to write a whole bunch of articles on that www intended to learn boost libraries in a 'boost for dummies' way. Unfortunately my gaming habbit eats too much time at the moment. Wkr, me
gast128 <gast128@hotmail.com> writes:
Nice! But it looks wrong at step 1.
The bjam commands you show there do not generate batch files as you claim. They build the Boost libraries!
Yes you are right, I hope I did communicate it in that way.
This should correspond to the following command line: 1. bjam "-sBUILD=debug <runtime-link>dynamic <threading>multi" "-sTOOLS=vc-7_1" 2. bjam "-sBUILD=release <runtime-link>dynamic <threading>multi" "-sTOOLS=vc-7_1" This gives two batch files: * zbuilddebug.zip * zbuildrelease.zip Seems to state very clearly that the commands will "give two batch files." I'm afraid your instructions will cause everything to be built twice. -- Dave Abrahams Boost Consulting www.boost-consulting.com
This should correspond to the following command line:
1. bjam "-sBUILD=debug <runtime-link>dynamic <threading>multi" "-
sTOOLS=vc-7_1"
2. bjam "-sBUILD=release <runtime-link>dynamic <threading>multi" "-
sTOOLS=vc-7_1"
This gives two batch files:
* zbuilddebug.zip * zbuildrelease.zip
Seems to state very clearly that the commands will "give two batch files." I'm afraid your instructions will cause everything to be built twice.
Ok I see the confusion. I meant that I have already wrapped above command line in two batch files. That's what happen if people are not grown up with English... Wkr, me
On Jan 30, 2006, at 11:17 AM, David Abrahams wrote:
What do you wish someone had explained to you? With what did you need hand-holding?
Also, it would be nice if the portions of the current release which work with gcc 4.x were identified as part of the "getting started" documentation. Also a pointer to the "LIBS= --with-foo_library" bjam option or the configure script "--with-libraries=foo_library" option would be helpful in working around the compile errors with gcc 4.x. Regards, -Steve -------- Steve Byan <smb@egenera.com> Software Architect Egenera, Inc. 165 Forest Street Marlboro, MA 01752 (508) 858-3125
Steve Byan <smb@egenera.com> writes:
On Jan 30, 2006, at 11:17 AM, David Abrahams wrote:
What do you wish someone had explained to you? With what did you need hand-holding?
Also, it would be nice if the portions of the current release which work with gcc 4.x were identified as part of the "getting started" documentation.
I don't think it makes sense to single out gcc 4.x, since there are lots of other compilers, and the answers may be different for each x. I *do* think it would make sense if there were a prominent section called, "What works on my compiler?" that has some preliminary explanation and a link to: http://engineering.meta-comm.com/boost-regression/1_33_0/user/summary_releas... suitably adjusted for 1.34, of course. I will definitely cover this in my talk, thanks!
Also a pointer to the "LIBS= --with-foo_library" bjam option
I recognize "--with-foo_library," but what is "LIBS=" supposed to to?
or the configure script "--with-libraries=foo_library" option would be helpful in working around the compile errors with gcc 4.x.
Doesn't the table at http://www.boost.org/more/getting_started.html#step5 contain a pointer to the --with-foo_library option? -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Jan 30, 2006, at 5:43 PM, David Abrahams wrote:
Also a pointer to the "LIBS= --with-foo_library" bjam option
I recognize "--with-foo_library," but what is "LIBS=" supposed to to?
Sorry, it's a makefile variable; my internal parser isn't working too well today. Ignore the "LIBS="
or the configure script "--with-libraries=foo_library" option would be helpful in working around the compile errors with gcc 4.x.
Doesn't the table at http://www.boost.org/more/getting_started.html#step5 contain a pointer to the --with-foo_library option?
Yep, that's good. I found the option by reading the configure script. Regards, -Steve -------- Steve Byan <smb@egenera.com> Software Architect Egenera, Inc. 165 Forest Street Marlboro, MA 01752 (508) 858-3125
Hey David- I'm a huge fan of examples. Most (all?) boost libraries have examples, but it would be nice to get many, many more. There are a ton of great things in boost. To me it would be inspiring for a person new to boost to look through them. I know everytime I did something new with boost, I caught myself saying, "C++ is so freaking cool." Simple examples of not just how but why to use a library would be great. A person new to boost would love to see bind, the iterator stuff, stream stuff... basically all the stuff that was hard to use with STL but really easy and slick in boost. When I first read about transform_iterator and more specifically iterator_facade, I was so happy. Now, I could put iterators on all my data... then I found bind... wow! I can do all sorts of functional stuff! In other words, chain the simple examples together. On 1/30/06, David Abrahams <dave@boost-consulting.com> wrote:
I'm giving a talk about getting started with Boost (https://www.cmpevents.com/SDw6/a.asp?option=G&V=3&id=271893) and I thought it would be a good idea to solicit input from those who have recently gone through the process. What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated.
Thanks,
-- Dave Abrahams Boost Consulting www.boost-consulting.com
_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users
Chris Goller wrote:
When I first read about transform_iterator and more specifically iterator_facade, I was so happy. Now, I could put iterators on all my data... then I found bind... wow! I can do all sorts of functional stuff!
In other words, chain the simple examples together.
Interesting! I agree that Boost libraries that have synergies should call them out in their docs. The idea of a central location on Boost.org dedicated to the whiz-bang productivity boosters (pun intended) might be a good grabber, too. I'm a big believer in the "hello world" example -- all good documentation should have one. Why not Boost.org as well? -- Eric Niebler Boost Consulting www.boost-consulting.com
Chris Goller wrote:
I'm a huge fan of examples. Most (all?) boost libraries have examples, but it would be nice to get many, many more. There are a ton of great things in boost. To me it would be inspiring for a person new to boost to look through them.
I second that; learning by example is a great way to get a kickstart on how to use a certain library, without having to dig through all the options to know what you actually want... if it wasn't for the examples, I would have a lot worse time learning boost!
I know everytime I did something new with boost, I caught myself saying, "C++ is so freaking cool." Simple examples of not just how but why to use a library would be great.
Yeah, maybe this calls for a some sort of wiki-like approach - I'm pretty sure a lot of developers found out neat things to do with Boost libraries of which they are willing to share code snippets... perhaps this is an idea for Boost, to make some sort of code snipped collection ? Just my thoughts on this... Regards, Leon Mergen
Chris Goller <goller@gmail.com> writes:
Hey David-
I'm a huge fan of examples. Most (all?) boost libraries have examples, but it would be nice to get many, many more. There are a ton of great things in boost. To me it would be inspiring for a person new to boost to look through them.
I know everytime I did something new with boost, I caught myself saying, "C++ is so freaking cool."
Could you give a few examples? When you've been around Boost and C++ as long as I have, you tend to lose touch with what will wow people. It would be really helpful to know what kinds of things you did that made you say that. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On 01/02/06, David Abrahams <dave@boost-consulting.com> wrote:
Chris Goller <goller@gmail.com> writes:
I know everytime I did something new with boost, I caught myself saying, "C++ is so freaking cool."
Could you give a few examples? When you've been around Boost and C++ as long as I have, you tend to lose touch with what will wow people. It would be really helpful to know what kinds of things you did that made you say that.
For me it was discovering Boost.Lambda. I had learned bind1st and bind2nd and really didn't understand why this functional programming was such a big deal since it was just so messy. Just a simple sort( c.begin(), c.end(), *_2 < *_1 ) really drives home the brilliance of Lambda for me. Functional-style programming just started making sense, and I realised how incredibly cool it was that this could be done in C++ with no specific language support. Of course then Lambda got upgraded ( or maybe I just hadn't found it before ) to include switches and conditionals and exceptions and nearly everything you can do in C++ and I got amazed again. ~ Scott McMurray
Hi, I would advise new Boost users to spend the time to read at least the introduction of each library to try to grasp the scope of Boost. I know it is quite time-consuming and ways to make that task easier are welcome. A 5-15 line description for each library in addition to the current 1-line description would help. For each category, an introduction presenting and contrasting the libraries. When libraries overlap (Regex, Spirit, Xpressive...) which one to chose? I'd love a section "STL booster" that would gather and organize libraries that might be useful to process an STL container. A section "Boost Essentials" that would include filesystem, date-time, smart_ptr, timer... (they are the first libraries I have used). Which libraries will go to TR1 and does that mean that codes that compile with Boost will compile with the next version of C++ without boost? JCR "David Abrahams" <dave@boost-consulting.com> wrote in message news:87hd7lbsg9.fsf@boost-consulting.com...
I'm giving a talk about getting started with Boost (https://www.cmpevents.com/SDw6/a.asp?option=G&V=3&id=271893) and I thought it would be a good idea to solicit input from those who have recently gone through the process. What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated.
Thanks,
-- Dave Abrahams Boost Consulting www.boost-consulting.com
I haven't had time to read all the responses to this, so I apologize if I have duplicated someone else's reply. It would be good to know what the experienced users consider to be the "everyday" or "basic" parts of Boost. The safe casts come to mind. I guess what I'm thinking of is something along the lines of "even if you use nothing else from this library collection, the following minimum set will help you write safer C++ code." I suspect that many of us first start using Boost because we're trying to solve some specific problem. (I was looking for a platform-neutral filesystem library.) We find the library we need and we use it. Then we have another problem to solve, so we find the library that helps there. Then one day we have the time to read through all of the library descriptions and we find things that we want to use, and we realize that we should go through all of the code we have written since we started using Boost, and replace error prone things with better Boost things. But by then we don't have time/our code has worked reliably for quite a while/something else stops us, and we can't really do that. It would have been nice to have read about those useful, basic things in the beginning. Other than that, the only thing you might add are testimonials on the home page. Everything I have used (and it's a whole lot more than the filesystem library by now) just works. My experience with other open source code has not been so seamless and easy, so I really appreciate this about Boost, and I thank all those who have contributed to it. - Rush
Rush Manbert <rush@manbert.com> writes:
I haven't had time to read all the responses to this, so I apologize if I have duplicated someone else's reply.
It would be good to know what the experienced users consider to be the "everyday" or "basic" parts of Boost. The safe casts come to mind. I guess what I'm thinking of is something along the lines of "even if you use nothing else from this library collection, the following minimum set will help you write safer C++ code."
_Great_ idea!
I suspect that many of us first start using Boost because we're trying to solve some specific problem. (I was looking for a platform-neutral filesystem library.) We find the library we need and we use it. Then we have another problem to solve, so we find the library that helps there. Then one day we have the time to read through all of the library descriptions and we find things that we want to use, and we realize that we should go through all of the code we have written since we started using Boost, and replace error prone things with better Boost things. But by then we don't have time/our code has worked reliably for quite a while/something else stops us, and we can't really do that. It would have been nice to have read about those useful, basic things in the beginning.
I do plan an overview of the scope of Boost in the talk. Not that I can describe everything, but I can give some sense of what areas are covered.
Other than that, the only thing you might add are testimonials on the home page.
You're suggesting that I put the testimonials in my talk, or just that we add more testimonials to the home page?
Everything I have used (and it's a whole lot more than the filesystem library by now) just works. My experience with other open source code has not been so seamless and easy, so I really appreciate this about Boost, and I thank all those who have contributed to it.
Can we use that one? :) -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Rush Manbert <rush@manbert.com> writes:
<snip>
Other than that, the only thing you might add are testimonials on the home page.
You're suggesting that I put the testimonials in my talk, or just that we add more testimonials to the home page?
Sorry, home page, not talk.
Everything I have used (and it's a whole lot more than the filesystem library by now) just works. My experience with other open source code has not been so seamless and easy, so I really appreciate this about Boost, and I thank all those who have contributed to it.
Can we use that one? :)
Sure. But Scott Meyers would carry more weight. ;-) - Rush
Rush Manbert <rush@manbert.com> writes:
David Abrahams wrote:
Rush Manbert <rush@manbert.com> writes:
<snip>
Other than that, the only thing you might add are testimonials on the home page.
You're suggesting that I put the testimonials in my talk, or just that we add more testimonials to the home page?
Sorry, home page, not talk.
Everything I have used (and it's a whole lot more than the filesystem library by now) just works. My experience with other open source code has not been so seamless and easy, so I really appreciate this about Boost, and I thank all those who have contributed to it.
Can we use that one? :)
Sure. But Scott Meyers would carry more weight. ;-)
Maybe, but Scott doesn't program for a living. He'll never have the perspective of an in-the-trenches C++ programmer discovering how Boost has just made his life easier, so he could never say anything like that. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Rush Manbert wrote:
I haven't had time to read all the responses to this, so I apologize if I have duplicated someone else's reply.
It would be good to know what the experienced users consider to be the "everyday" or "basic" parts of Boost. The safe casts come to mind. I guess what I'm thinking of is something along the lines of "even if you use nothing else from this library collection, the following minimum set will help you write safer C++ code."
Top of the list, as far as I'm concerned, has to be smart pointers. You would not see me using traditional memory allocation on the heap any more, unless some other third-party library insists on it. Spending ages debugging memory leaks and tracking down missing "delete"s is now mercifully a distant memory. Paul
David Abrahams wrote:
What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated.
From my POV as a user and recent contributor my comments are: 1. It took me a long time for me to realise that a large proportion of Boost is header-only and can be used without pre-building any libraries (archives & shared objects). 2. It is also not immediately clear that there is a large amount of interdependency between Boost libraries. This information would be particularly useful when trying to resolve compilation problems e.g if Boost.b & Boost.c both use Boost.a, if you can't get 'a' to compile then you don't stand a cat in hell's chance with b and/or c. IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section. 3. Boost's sheer size makes it difficult to document. From the responses so far it's obvious that different users have their own personal favourite sections. I find that I discover something new every day, usually thinking "If only I had discovered that six months ago I could have saved so much time!" The ultimate solution would be to have a problem oriented section in the docs, i.e. if you are trying to do this, then we suggest you try these libraries. If we assume that each library was constructed in order to fill a need and/or solve a problem (and not just for intellectual amusement) then these needs/problems could be collated into a single section. 4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up. HTH Jim Douglas
Jim Douglas <jim@dramatec.co.uk> writes:
David Abrahams wrote:
What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated.
From my POV as a user and recent contributor my comments are:
1. It took me a long time for me to realise that a large proportion of Boost is header-only and can be used without pre-building any libraries (archives & shared objects).
2. It is also not immediately clear that there is a large amount of interdependency between Boost libraries. This information would be particularly useful when trying to resolve compilation problems e.g if Boost.b & Boost.c both use Boost.a, if you can't get 'a' to compile then you don't stand a cat in hell's chance with b and/or c.
We have to be careful about qualitative statements like that one. Compared to many large-scale libraries, Boost is highly decoupled.
IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section.
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option? That's something I can cover in my talk.
3. Boost's sheer size makes it difficult to document. From the responses so far it's obvious that different users have their own personal favourite sections. I find that I discover something new every day, usually thinking "If only I had discovered that six months ago I could have saved so much time!"
The ultimate solution would be to have a problem oriented section in the docs, i.e. if you are trying to do this, then we suggest you try these libraries. If we assume that each library was constructed in order to fill a need and/or solve a problem (and not just for intellectual amusement) then these needs/problems could be collated into a single section.
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case. But if you could be more specific -- i.e. write some of it -- then maybe the rest of us could pick up on what you're doing and see how it would work.
4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up.
What would be better, "the boost serialization of a style espoused by Robert Ramey library?" ;-) -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes: Compared to many large-scale libraries, Boost is highly decoupled.
Such as...?
IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section.
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option?
I am aware of it, but the output is not very user friendly and AFAIK you cannot decouple the test functions to show what is required for "normal" use. [...]
The ultimate solution would be to have a problem oriented section in the docs, i.e. if you are trying to do this, then we suggest you try these libraries. If we assume that each library was constructed in order to fill a need and/or solve a problem (and not just for intellectual amusement) then these needs/problems could be collated into a single section.
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case.
Does *anyone* use them?
But if you could be more specific -- i.e. write some of it -- then maybe the rest of us could pick up on what you're doing and see how it would work.
Hmm. I'll think about that - after 1.34 is released :-)
4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up.
What would be better, "the boost serialization of a style espoused by Robert Ramey library?" ;-)
LOL. But I think you get what I mean. Jim
Jim Douglas <jim@dramatec.co.uk> writes:
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes: Compared to many large-scale libraries, Boost is highly decoupled.
Such as...?
IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section.
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option?
I am aware of it, but the output is not very user friendly
I agree with that. John, do you think it would be possible to generate a simple list of boost library dependencies, e.g. parameter depends on mpl, type_traits, config, utility, and preprocessor
and AFAIK you cannot decouple the test functions to show what is required for "normal" use.
I don't know what you mean there about the "test functions"
The ultimate solution would be to have a problem oriented section in the docs, i.e. if you are trying to do this, then we suggest you try these libraries. If we assume that each library was constructed in order to fill a need and/or solve a problem (and not just for intellectual amusement) then these needs/problems could be collated into a single section.
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case.
Does *anyone* use them?
Yes, many people use them.
But if you could be more specific -- i.e. write some of it -- then maybe the rest of us could pick up on what you're doing and see how it would work.
Hmm. I'll think about that - after 1.34 is released :-)
Hehehe.
4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up.
What would be better, "the boost serialization of a style espoused by Robert Ramey library?" ;-)
LOL. But I think you get what I mean.
Really, I don't. -- Dave Abrahams Boost Consulting www.boost-consulting.com
I think there is a distinction that needs to be made between 1) attracting folks to Boost 2) helping out those who are giving it a shot for the first time and know nothing about it. I discovered it by recommendation from a colleague, and think it's the best way to advertise. That being said, (2) is still and issue for me... I have found the mailing list archives proved helpful, but took an inordinate amount of time to search through. Is it possible to take threads in the mailing lists that look something like this: - A: I have problem XYZ - B-Z: Oh, you need to do this - A: That fixed it, thanks! and convert them to a FAQ or additional documentation? There is a *ton* of useful information in the mailing lists, an organic conglomeration of docs that are not based on what the writer of the library thinks you'll need to know but rather what experience has taught us people want to know. The problem is it's a pain to parse through. Even if that's too much work, a FAQ/tips and tricks/searching hints on how to get the most out of the data that is already in existence would have been a big help. Blessings, Foster -- Foster T. Brereton - Computer Scientist Software Technology Lab, Adobe Systems Incorporated fbrereto@adobe.com -- http://opensource.adobe.com
Foster Brereton <fosterb.boost@gmail.com> writes:
I think there is a distinction that needs to be made between 1) attracting folks to Boost 2) helping out those who are giving it a shot for the first time and know nothing about it.
I discovered it by recommendation from a colleague, and think it's the best way to advertise. That being said, (2) is still and issue for me...
Good; it's (2) that I asked about, so I appreciate that you are addressing it.
I have found the mailing list archives proved helpful, but took an inordinate amount of time to search through. Is it possible to take threads in the mailing lists that look something like this: - A: I have problem XYZ - B-Z: Oh, you need to do this - A: That fixed it, thanks! and convert them to a FAQ or additional documentation?
Maybe. Who would do that, and how?
There is a *ton* of useful information in the mailing lists, an organic conglomeration of docs that are not based on what the writer of the library thinks you'll need to know but rather what experience has taught us people want to know. The problem is it's a pain to parse through.
The only way to make it less painful would be to add some kind of automation, I guess. Any ideas?
Even if that's too much work, a FAQ/tips and tricks/searching hints on how to get the most out of the data that is already in existence would have been a big help.
When you find some tricks, let us know! Seriously, you're in a better position to do this than people who don't need to search the mailing list for that kind of answer. When I search, it's usually because I remember a particular conversation and I want to point someone at it. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Foster Brereton <fosterb.boost@gmail.com> writes: ...
There is a *ton* of useful information in the mailing lists, an organic conglomeration of docs that are not based on what the writer of the library thinks you'll need to know but rather what experience has taught us people want to know. The problem is it's a pain to parse through.
The only way to make it less painful would be to add some kind of automation, I guess. Any ideas?
Even if that's too much work, a FAQ/tips and tricks/searching hints on how to get the most out of the data that is already in existence would have been a big help.
When you find some tricks, let us know! Seriously, you're in a better position to do this than people who don't need to search the mailing list for that kind of answer. When I search, it's usually because I remember a particular conversation and I want to point someone at it.
Hmmm, it would be nice to be able to google the mailing list archives via google-groups. I haven't thought about exactly why, but I seem to find google-groups more productive than the gmane archive search. Jeff Flinn
"Jeff Flinn" <TriumphSprint2000@hotmail.com> writes:
David Abrahams wrote: ...
When you find some tricks, let us know! Seriously, you're in a better position to do this than people who don't need to search the mailing list for that kind of answer. When I search, it's usually because I remember a particular conversation and I want to point someone at it.
Hmmm, it would be nice to be able to google the mailing list archives via google-groups.
You can at least do that for the developer list. http://groups.google.com/group/boost-list?lnk=srg I don't know how Google decided to include the developer list; you might contact them if you want the user list included. And then there's always the google search of the mailing lists available on the Boost front page. -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
"Jeff Flinn" <TriumphSprint2000@hotmail.com> writes:
David Abrahams wrote: ...
When you find some tricks, let us know! Seriously, you're in a better position to do this than people who don't need to search the mailing list for that kind of answer. When I search, it's usually because I remember a particular conversation and I want to point someone at it.
Hmmm, it would be nice to be able to google the mailing list archives via google-groups.
You can at least do that for the developer list. http://groups.google.com/group/boost-list?lnk=srg
Great! Thanks Dave!
I don't know how Google decided to include the developer list; you might contact them if you want the user list included. And then
Done(at least the asking part). I've also asked for the spirit mailing lists as well.
there's always the google search of the mailing lists available on the Boost front page.
Not quite as nice as the google-groups layout. Also thanks for you other post on the http://archives.free.net.ph/splash/index.en.html link. Jeff Flinn
Jeff Flinn wrote:
David Abrahams wrote:
Foster Brereton <fosterb.boost@gmail.com> writes:
...
There is a *ton* of useful information in the mailing lists, an organic conglomeration of docs that are not based on what the writer of the library thinks you'll need to know but rather what experience has taught us people want to know. The problem is it's a pain to parse through.
The only way to make it less painful would be to add some kind of automation, I guess. Any ideas?
Even if that's too much work, a FAQ/tips and tricks/searching hints on how to get the most out of the data that is already in existence would have been a big help.
When you find some tricks, let us know! Seriously, you're in a better position to do this than people who don't need to search the mailing list for that kind of answer. When I search, it's usually because I remember a particular conversation and I want to point someone at it.
Hmmm, it would be nice to be able to google the mailing list archives via google-groups. I haven't thought about exactly why, but I seem to find google-groups more productive than the gmane archive search.
I think you can use the technique described here to search boost-users on Google: http://lists.boost.org/boost-users/2005/07/12703.php I just tried it and it seems to work fine. - Rush
On 2/4/06, David Abrahams <dave@boost-consulting.com> wrote: [snip]
I have found the mailing list archives proved helpful, but took an inordinate amount of time to search through. Is it possible to take threads in the mailing lists that look something like this: - A: I have problem XYZ - B-Z: Oh, you need to do this - A: That fixed it, thanks! and convert them to a FAQ or additional documentation?
Maybe. Who would do that, and how?
My initial thought is that should be the responsibility of the library owner. Most of the time they're the one responding to the user's issues. Even if they're not they should have a pulse on the mailing lists as it pertains to their library so as to be aware an issue has come up and has been resolved. I would imagine doing these updates piecemeal, as the questions come in and are answered, would make for light work on a regular basis, and would amount to a significant (and relevant) piece of documentation. Another alternative/extension to this idea would be to have the one who posted the question reflect their answer/experience to a Wiki or some other collaborative page. It could take some of the strain off the developers. A "boost-wikipedia" in my opinion would go very far, giving those who have authority on a library the ability to contribute and develop the docs one piece at a time. They are the ones who are actually using the code, after all, and would have the best insights on what content would make the most impact. If it had the blessing and support of the boost developers behind it, it could have the momentum it needs to be useful. Blessings, Foster -- Foster T. Brereton - Computer Scientist Software Technology Lab, Adobe Systems Incorporated fbrereto@adobe.com -- http://opensource.adobe.com
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes:
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes:
IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section.
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option?
I am aware of it, but the output is not very user friendly
I agree with that. John, do you think it would be possible to generate a simple list of boost library dependencies, e.g.
parameter depends on mpl, type_traits, config, utility, and preprocessor
With a bit of additional scripting that would be possible now.
and AFAIK you cannot decouple the test functions to show what is required for "normal" use.
I don't know what you mean there about the "test functions"
If you run bcp, every library shows up as depending on test and mpl (because test uses mpl). Boost.test is only used for regression testing. When you deploy a Boost library in a project, Boost.test is no longer of any use/interest, but the chosen library may still depend on others in the suite. What we need is the ability to take Boost.test (and its dependencies) out of the equation so that we can see what the dependency graph looks like when the individual libraries are deployed. [...]
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case.
Does *anyone* use them?
Yes, many people use them.
OK I was being slightly flippant, but some examples of would help identify use cases for those particular libraries. IIRC when the laser was invented it was described as "A solution looking for a problem". I guess you could apply that to Boost as "A bunch of general purpose solutions looking to solve specific problems". Some variation of that theme might make a good Powerpoint slide for your presentation :-)
4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up.
What would be better, "the boost serialization of a style espoused by Robert Ramey library?" ;-)
LOL. But I think you get what I mean.
Really, I don't.
OK a really good example is "signals". To a Unix/QNX programmer a signal has a very specific meaning, and for a while I didn't bother to look further because I assumed that Boost.signals was basically a set of C++ wrappers around the Unix functions (same applied to Boost.threads). It wasn't until I read the Karlsson book that I realised they were quite different. That's the problem. I'm not sure of the solution - but I think we have floated some useful ideas... Jim
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Jim Douglas
[...]
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case.
Does *anyone* use them?
Yes, many people use them.
OK I was being slightly flippant, but some examples of would help identify use cases for those particular libraries.
The problem is that these libraries--particularly the MPL and the pp-lib--are general-purpose to the point of being language-like rather than library-like. Enumerating use cases for these libraries is like enumerating use cases of looping or branching. Listing several use cases doesn't even slightly do justice to the underlying concepts, and they become nothing more than complex examples. IMO, the approach of trying to solve a particular problem, searching for a library that solves (or helps to solve) the particular problem, and expecting to find one of these types of libraries is flawed. It works the other way around. Instead, you invest the time necessary to understand what kind of things these libraries can do, etc. (which doesn't imply mastering the library). Later, when you evaluate possible solutions to a particular problem, you often have more realistic possibilities because these libraries remove design limitations that would otherwise cause you to reject a possibility. Because of that, real-world use cases of these libraries are usually completely unrelated to what these libraries do. The libraries themselves are just used to implement "something else" that otherwise couldn't be easily implemented. (I'm having a hard time formulating what I'm thinking, so perhaps I'm not describing what I'm trying to get at very clearly.) Any given interface falls at some point between completely specific to completely general. An interface that is completely specific has only one specific use case. Such an interface is not a _library_ interface. An interface that is completely general has an infinite set of use cases that covers an infinitely broad scope. Such an interface cannot exist. Libraries in Boost vary greatly in where they fall along this specific->general axis. The more general a library is, the more difficult it is to describe the library in terms of use cases. When a library approaches being completely general, effective use requires a significant amount of lateral thought by the user, not use cases in the documentation. Examples (as opposed to use cases) in the documentation exist mainly as an attempt to induce the necessary lateral thought, not to show what problems the library solves. Hopefully, that made any kind of sense. I've given this a lot of thought over the last several years for the pp-lib docs, as this is a typical complaint ("The docs don't tell me in what situations the library is useful."). I still don't know what I could write to do that, and, at this point, I'm starting to think that attempting to do that is counterproductive. Regards, Paul Mensonides
Paul Mensonides wrote: [...] I like what you wrote here:
Any given interface falls at some point between completely specific to completely general. An interface that is completely specific has only one specific use case. Such an interface is not a _library_ interface. An interface that is completely general has an infinite set of use cases that covers an infinitely broad scope. Such an interface cannot exist. Libraries in Boost vary greatly in where they fall along this specific->general axis.
I may have used the words concrete->abstract axis. It might be a basis on which to rate the libraries with a "fuzzy" classification that indicates position on the axis and spread of coverage. E.g. Boost.Crc even contains some pre-defined ready-to-use concrete types, whereas at the other extreme Boost.MPL is an abstract framework.
The more general a library is, the more difficult it is to describe the library in terms of use cases. When a library approaches being completely general, effective use requires a significant amount of lateral thought by the user, not use cases in the documentation.
From a purely practical POV here is the communications problem: I have a piece of software to construct and I have sufficient confidence that I can write it in C/C++ in N weeks from the ground up. How can I extract enough information from the Boost docs to identify those Boost libs that are applicable to my problem domain? How can I then evaluate those libraries so identified, enough to be convinced that the full *learning* time plus deployment time will result in the project lasting N weeks or less? And so it goes on with quality issues etc...
Examples (as opposed to use cases) in the documentation exist mainly as an attempt to induce the necessary lateral thought, not to show what problems the library solves.
Examples - yes, I can't get enough of them. A couple of small caveats: a) There is a danger that you might not relate to an example if you can't see that by changing a few things you can put it to good use in your particular context. OK so you can't please all of the people all of the time. b) Examples need to be grounded in the real world - which tenuously links to use cases. 'foo/bar' examples should be banned :-)
Hopefully, that made any kind of sense.
A great deal. Thanks Jim
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Jim Douglas
I may have used the words concrete->abstract axis. It might be a basis on which to rate the libraries with a "fuzzy" classification that indicates position on the axis and spread of coverage. E.g. Boost.Crc even contains some pre-defined ready-to-use concrete types, whereas at the other extreme Boost.MPL is an abstract framework.
And the pp-lib is a framework that is more general still.
From a purely practical POV here is the communications problem:
I have a piece of software to construct and I have sufficient confidence that I can write it in C/C++ in N weeks from the ground up.
How can I extract enough information from the Boost docs to identify those Boost libs that are applicable to my problem domain?
For a library approaching full generality, it is applicable to just about *every* domain, but that doesn't mean that it should always be used. Whether or not it should be has to be determined on a case by case basis in comparison with other possibilities.
How can I then evaluate those libraries so identified, enough to be convinced that the full *learning* time plus deployment time will result in the project lasting N weeks or less?
You can't because it doesn't work that way. For libraries like these, you learn them to increase your general toolset which can later be applied to any number of projects. Note that this is a lot like learning a language and the accompanying techniques outside of the context of a real-world project with real-world deadlines.
Examples (as opposed to use cases) in the documentation exist mainly as an attempt to induce the necessary lateral thought, not to show what problems the library solves.
Examples - yes, I can't get enough of them. A couple of small caveats:
a) There is a danger that you might not relate to an example if you can't see that by changing a few things you can put it to good use in your particular context. OK so you can't please all of the people all of the time.
The danger is not that you might not relate to an example. The danger is that you might not "get it". Meaning not that you don't understand what the example does, but that you might not achieve the perspective (or the beginnings of the perspective) that the example hints at. Does this mean that less people use such a library? Yes, it does, and, in its way, that is a good thing. Because such a library can be used just about anywhere, it takes both a reasonable amount of understanding and a reasonably correct perspective to apply wisely. It shouldn't be thrown at any possible problem where it could be used. Instead, a smaller number of people (that know what they're doing) use libraries like this to implement other things (often still fairly general) that can be used effectively by more people. As a practical example of this effect, the pp-lib can be used to generate code for a template metaprogramming framework (e.g. the MPL). The MPL can, in turn, be used to implement a binary literal utility (see Dave and Aleksey's book). The binary literal utility can be used to implement some sort of message cracking function. Each step down this path represents a decrease in generality. With each decrease, the number of people that are likely to use it correctly increases (sometimes dramatically). This occurs because the higher the generality, the higher the number of possible malconceived uses (as well as the higher the number of well-conceived uses). The person that uses the binary literal utility (which is fairly easy to use) is also ultimately using the pp-lib, though indirectly. What I'm getting at here is that although the number of direct users of something as general as the pp-lib or the MPL may be fewer, the number of indirect users may be much greater. All of this isn't about documentation per se, but rather that the goal of a library is not always about maximum number of direct users.
b) Examples need to be grounded in the real world - which tenuously links to use cases. 'foo/bar' examples should be banned :-)
Presumably you mean "contrived" examples. I think that depends heavily on what a piece of code is supposed to be an example of. If you make examples too complex, the point that it is trying to make is lost in the particular details of the example. Then the example itself becomes a cookbook interface when it is really supposed to be an example of something else. Using an example to bring a very general interface or group of interfaces all the way down the generality axis to a particular use case virtually requires that the example be complex. Even for something as simple as a binary literals example requires dealing with domain-specific issues (like octal literals) that have nothing to do with the library being used to implement it. The problem that I have with your viewpoint is that you seem to be expecting even very general libraries to show where they're useful in concrete, specific examples. By definition, a finite set of use case examples doesn't even come close to being sufficent. A different tack is needed. Instead, examples for a highly general library should focus on the perspective and creativity required to apply the highly general library to an unbounded number of specific situations. So, the purpose of such examples aren't about use cases, they're about a perspective-shift that, if attained, allows users to _identify_ use cases. If that is what it is about, whether or not an example is practical or contrived is a non-issue. I don't, OTOH, have a problem with your viewpoint when it is applied to less general libraries where the number of use cases is relatively small or falls into a relatively confined scope. I just don't think that the whole concept of "how to do documentation" can fit into a unilateral mold for all types of libraries. I don't think that the documentation for highly general libraries like the MPL or the pp-lib, for example, should be "dumbed down" (i.e. made concrete enough) to the point of being understandable by all users. I actually think that that is dangerous. Such tools can create gigantic messes if not used wisely (e.g. if they get used mainly for the sake of being clever). For those that are actually interested in expanding their perspective (as opposed to just getting a job done), then the learning of these kinds of tools should fall outside of a "project that is supposed to take N weeks or less" because such learning implies not just learning what each interface does, but how to identify use cases when you come across them. Documentation that induces that ability in users is a lot harder to write than one might think based on a casual first glance. I think it's worth pointing out that for such libraries, the reference documentation alone (that includes only contrived examples) is enough for someone that is actually motivated to learn these things. I'm not the original author of the pp-lib, for example, yet I understand it completely and know how to identify use cases when I come across them--simply because I invested the time and effort to shift the way that I view things (and I'm not the only one). If more C or C++ programmers were familiar with functional programming, with metalevel programming (such as the macro systems in Lisp or Scheme), and with lazy evaluation (such as in Haskell) rather than just imperative runtime-level strict-evaluation programming, this stuff would be a lot easier for users to understand and apply. It really is a pity that the imperative paradigm is, by definition, a superset of the functional paradigm, yet so much of the functional paradigm is unused or forgotten. Don't misunderstand me. I am not one who thinks that the functional paradigm is superior. In fact, I think that the functional paradigm does not adequately represent reality and, as often as not, that a functional solution requires a great deal of logical contortion. [Some models in software are naturally imperative while others are naturally functional. Any time that you use an imperative design to solve a functional model or vice versa, it causes logical contortion that complicates the design. Sometimes that complication is worth it for other reasons (e.g. efficiency or provability)--there are always tradeoffs.] Nevertheless, there is a lot of good stuff that is common in functional designs that shouldn't be ignored but largely has been. Regards, Paul Mensonides
"Paul Mensonides" <pmenso57@comcast.net> writes:
examples for a highly general library should focus on the perspective and creativity required to apply the highly general library to an unbounded number of specific situations. So, the purpose of such examples aren't about use cases, they're about a perspective-shift that, if attained, allows users to _identify_ use cases.
Extra: Paul Hits Nail On Head! Well said. -- Dave Abrahams Boost Consulting www.boost-consulting.com
Jim Douglas <jim@dramatec.co.uk> writes:
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes:
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes:
IMHO it is high time that someone produced a dependency graph, or each library document had a "uses" section.
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option?
I am aware of it, but the output is not very user friendly
I agree with that. John, do you think it would be possible to generate a simple list of boost library dependencies, e.g.
parameter depends on mpl, type_traits, config, utility, and preprocessor
With a bit of additional scripting that would be possible now.
and AFAIK you cannot decouple the test functions to show what is required for "normal" use.
I don't know what you mean there about the "test functions"
If you run bcp, every library shows up as depending on test and mpl
I don't think so. When I tried it yesterday there was no mention of Boost.Test headers in the Boost.Parameter dependency report.
Yeah... some libraries are so general-purpose (e.g. lambda, mpl, preprocessor) that it's hard for me to say anything that most people will identify as their use case.
Does *anyone* use them?
Yes, many people use them.
OK I was being slightly flippant, but some examples of would help identify use cases for those particular libraries.
The preprocessor library has a pretty good (if I do say so myself) tutorial with a real-world example in it.
IIRC when the laser was invented it was described as "A solution looking for a problem". I guess you could apply that to Boost as "A bunch of general purpose solutions looking to solve specific problems". Some variation of that theme might make a good Powerpoint slide for your presentation :-)
No thanks. Boost libraries are very nicely targeted at specific problem domains.
4. The single word naming of the libraries can lead to ambiguities and misunderstanding e.g. "serialization" means different things to different people and requires a full paragraph to explain, and IMHO "thread" is somewhat misleading. Other names mean nothing to me so I have to go and look them up.
What would be better, "the boost serialization of a style espoused by Robert Ramey library?" ;-)
LOL. But I think you get what I mean.
Really, I don't.
OK a really good example is "signals". To a Unix/QNX programmer a signal has a very specific meaning, and for a while I didn't bother to look further because I assumed that Boost.signals was basically a set of C++ wrappers around the Unix functions (same applied to Boost.threads). It wasn't until I read the Karlsson book that I realised they were quite different.
Fine, but serialization and threads? C'mon. -- Dave Abrahams Boost Consulting www.boost-consulting.com
If you run bcp, every library shows up as depending on test and mpl
I don't think so. When I tried it yesterday there was no mention of Boost.Test headers in the Boost.Parameter dependency report.
It depends how you run it: basically it scans files for file dependencies so: If you pass it a list of *library names* to scan, and those libraries have tests that depend on "whatever" (Boost.Test etc) then you get a very fat dependency graph. However if you're more disciminating and pass the name of the headers you use, then you get a list of dependencies for those headers, for example: bcp --list regex => Big fat list including Boost.Test and Boost.Thread bcp --list regex.hpp => Slimline list, just what the headers and source depend on. bcp --scan --list myfile.cpp => Whatever Boost headers/source myfile.cpp depends on. And yes this is all in the docs :-) Also don't forget that the output from bcp is made more verbose by the need to create a dependency chart that works for any compiler: your specific compiler may need only a fraction of what bcp reports, in some cases anyway. Someone asked about producing a library dependency chart: there are two problems with that: There are many libraries that depend on just one or two files in otherwise quite large libraries such as MPL, Preprocessor, Type Traits etc. Do these depend on those libraries? It's quite hard to map some header files (those direcly in boost/) to library names: we could make a manual list to do the job, but it would be a non-stop job keeping it up to date. What I will investigate though is collapsing the output from bcp --list so that boost/foo/* all map to a single entry boost/foo libs/foo/* all map to a single entry libs/foo which would cut down the list output a lot. John.
Jim Douglas <jim@dramatec.co.uk> writes:
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option?
I am aware of it, but the output is not very user friendly
I agree with that. John, do you think it would be possible to generate a simple list of boost library dependencies, e.g.
parameter depends on mpl, type_traits, config, utility, and preprocessor
With a bit of additional scripting that would be possible now.
Can you contribute such a script? -- Dave Abrahams Boost Consulting www.boost-consulting.com
David Abrahams wrote:
Jim Douglas <jim@dramatec.co.uk> writes:
Do you know about http://www.boost.org/tools/bcp/bcp.html and its --report option?
I am aware of it, but the output is not very user friendly
I agree with that. John, do you think it would be possible to generate a simple list of boost library dependencies, e.g.
parameter depends on mpl, type_traits, config, utility, and preprocessor
With a bit of additional scripting that would be possible now.
Can you contribute such a script?
I'll see what I can do... Jim
Hi, Although this thread has indeed moved on to many things I just wanted to add my 2 cents here in response to Dave's original questions: 1) To learn the more general and abstract libraries in boost I really like as many differing examples as possible. Even when I get the general idea of what a library is for I often need something to fire my imagination. And simple examples and additional case studies really help me. (I'm not trying to negate or contravene anything that has been said up to now on this subject, I'm just stating that this is how I seem to learn and work best). Additionally, sometimes I understand an abstraction easier if I start with some concrete example and work my way up so to speak. I would put the PP, MPL, WAVE and SPIRIT libraries in this category for myself. For example, I haven't a clue what to do yet with the Wave library even though I know what it's for. I keep looking for some example of when/where/how to use it in a compiler or IDE tool chain, to no avail. So what looks like a fantastic addition to boost will certainly go under-utilized by at least one programmer! 2) I use boost a fair amount of the time as a cross-platform abstraction layer for C++. It provides almost everything I need in system services, except for XML support and internationalization. So I throw in ICU and Xerces and that pretty much covers my needs. But when it comes to a cross platform build or build environment, well as others have remarked, bjam is still too esoteric to use! So I would greatly appreciate an overview of all that is in boost (or at least the relevant seminal parts) that lend themselves to creating this type of cross-platform abstraction layer with a cross platform build environment and/or scripts. If this isn't possible (for whatever reason - such as bjam really is an incomprehensible tool and pain to script) then at least some documentation on the subject of how to create consistent cross platform builds (Win32, Linux and OS X for starters) will be greatly appreciated. Yours truly, Elisha
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users- bounces@lists.boost.org] On Behalf Of David Abrahams Sent: Monday, January 30, 2006 8:18 AM To: boost-users@lists.boost.org Subject: [Boost-users] Getting started with Boost: what did you need to know?
I'm giving a talk about getting started with Boost (https://www.cmpevents.com/SDw6/a.asp?option=G&V=3&id=271893) and I thought it would be a good idea to solicit input from those who have recently gone through the process. What do you wish someone had explained to you? With what did you need hand-holding? Based on this feedback I expect to make some improvements to the Boost website, also. Any information you can give me will be much appreciated.
Thanks,
-- Dave Abrahams Boost Consulting www.boost-consulting.com
_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users
Elisha Berns wrote:
(for whatever reason - such as bjam really is an incomprehensible tool and pain to script)
As someone who is far from an expert programmer or boost expert, I'd like to express a different opinion. bjam *is* difficult to learn at first. For me one reason was simply how alien it looks compared to an IDE or make. And until recently the documentation was simply incomprehensible. Although I'm really looking forward to the new documentation Dave is going to write, the existing documentation of Boost Build v2 is really not too bad for learning how to compile and link libraries and executables. If that's all you need to do, the documentation plus a few questions posted on the mailing list should get you up to speed. I agree there's a steep learning curve, but I found it surprisingly short. And once you've got the hang of it, building software on different platforms (I've done it on Windows, Linux, Solaris, MacOSX) is incredibly easy and can be done using a single Jamfile.
participants (1)
-
Chris Goller -
David Abrahams -
Deane Yang -
Elisha Berns -
Eric Niebler -
Foster Brereton -
gast128 -
Jeff Flinn -
Jim Douglas -
John Christopher -
John Maddock -
Leon Mergen -
me22 -
Michael Shapiro -
Paul Giaccone -
Paul Mensonides -
Rush Manbert -
Steve Byan