[C++-sig] Re: help building hello world example on Debian

[David Abrahams]

[Volodya/Rene -- Faheem makes some important points about our
documentation below]

Faheem Mitha <faheem at email.unc.edu> writes:

> Hi, Thanks for the quick and helpful reply. Replies follow.
>
> In what follows I'm going to try the obvious things and report what
> happens.
>
> 1) The first thing I am doing is copying the directory example to
> /tmp. I then tried
>
> faheem /tmp/example>bjam -sTOOLS=gcc test
> Unable to load Boost.Build: could not find build system.
> ---------------------------------------------------------
> /tmp/example/boost-build.jam attempted to load the build system by
> invoking
>
>    'boost-build ../../../tools/build/v1 ;'
>
> but we were unable to find "bootstrap.jam" in the specified directory
> or in BOOST_BUILD_PATH (searching
> /tmp/example/../../../tools/build/v1, /usr/share/boost-build).
>
> Ok. This obviously wants files elsewhere in the source directory 

I don't know what you mean.  Just read
http://www.boost.org/libs/python/doc/building.html#building_ext and
follow the directions there.  You just have to make a couple of small
edits to indicate where the Boost build system lives.

> eg (tools/build/vi). This is undesirable, as I don't want to have to
> always build my extensions inside the source directory.
>
> Looking at tools/build/vi, I see a lot of files ending with the words
> jam. I have all the relevant binary Debian packages installed, and the
> only place I see it is in
> /usr/share/doc/libboost-doc/HTML/tools/build/v1 which includes a few
> random files like python.jam, which do appear to correspond to the
> files in tools/build in the boost sources. Wonder if some of these
> files did not get copied by mistake.
>
> Regardless, these files should be part of a dev package, not a doc
> package if they are required for building.

I don't know anything about packages; I don't make the debian
distros.  You should talk to whoever is responsible for that.

> What is the difference between v1 and v2? Why should I be using one as
> opposed to the other?

v1 is supported.  v2 is prerelease.

>
> Does this correspond to the v1 and v2 of Boost Build? 

Yes.

> Should I be using v1? If so, why?

See above.

> 2) I then tried this command in the source directory.
>
> This gave me
>
> *******************************************************************
> skipping Boost.Python library build due to missing or incorrect
> configuration
>
> couldn't find Python.h in "/usr/local/include/python2.2"
>
> You can configure the location of your python installation by setting:
> PYTHON_ROOT    - currently "/usr/local"
> PYTHON_VERSION - The 2-part python Major.Minor version number (e.g.
>                  "2.2", NOT "2.2.1")  - currently "2.2"
>
> The following are automatically configured from PYTHON_ROOT if not
> otherwise set:
>
>     PYTHON_LIB_PATH       - path to Python library object; currently
>                           "/usr/local/lib/python2.2/config"
>     PYTHON_INCLUDES    - path to Python #include directories;
> currently "/usr/local/include/python2.2"
> *******************************************************************
>
> Ok. So I need to set some environmental variables. However, I don't
> want to have to set these environmental variables globally.
>
> http://www.boost.org/tools/build/v1/build_system.htm#setting_variables
> says I can set it in my Jamrules file. I have a Jamrules file in
> libs/python/example which says
>
> ***************************************************************
> ...
> # Edit this path to point at the root directory of your Boost
> # installation.  Absolute paths work, too.
> path-global BOOST_ROOT : ../../.. ;
> project boost : $(BOOST_ROOT) ;
> ******************************************************************
>
> Ok, putting
>
> path-global PYTHON_ROOT : /usr ;
> path-global PYTHON_VERSION : 2.3 ;
>
> in the Jamrules files seems to do the trick after a long compilation,
> and I get getting_started1.so  getting_started2.so in bin/example.

Whoo hoo!

> Suggestion. Add these lines above (or something similar) commented out
> to the Jamrules, since these will frequently need to be
> changed/adjusted depending on the system.
>
>> [Joel, the tutorial example is not a very good one in general; people
>> would like to be able to build extensions outside of their Boost tree.
>> I think you ought to base the "building" example on the one in
>> libs/python/example, and use project ids (e.g. @boost) as in that
>> Jamfile]
>
> Yes, I think it would be nice to have a tutorial where the
> configuration files are as detailed as possible. Preferably
> self-documenting.

That's a good idea.

>>> I would prefer not to have to do extensive configuration of other
>>> files, and I'd also prefer not to have to modify the jamfile if I
>>> moved it to a different location in the directory hierarchy. Can these
>>> preferences be satisfied?
>>
>> Yes; just use your boost-build file to indicate the location of the Boost
>> project.  
>
> If this refers to the files in tools/build/v1, I must again repeat
> that they are not installed on my system. If this is an error on the
> part of the Debian maintainer(s), I'd be happy to file a suitable bug
> report. Let me know.

If you want to build the Boost libraries or use Boost.Build for
building your own extensions, they're required.  I'm not qualified to
say whether the fact that they're missing is an error.

>> Please, which docs seem complicated and were confusing you?  We'd
>> like to improve them.
>
> Ok, here are some suggestions.

Thanks, these are much appreciated.

> 1) Please clarify which files correspond to the boost build system. 

Where should that be clarified?

> If these tools/build/v1 should be part of a binary installation,
> plese say so. 

It depends on your expectations of a binary installation, I guess.
If you want to do all your building with other build systems, you
probably don't need them.  That said, we recommend Boost.Build, at
least in order to see the proper command-lines.

> It is is not reasonable to expect people to build against a complete
> copy of the boost sources.

Actually, that is the expectation.

> 2) Also, all this v1/v2 stuff is unclear. My impression is that v1 is
> the "stable" version of the build system, and v2 is the unstable one,
> but it would be useful to say something about this explicitly.

Where should that be stated?

> 3) Make the tutorial example config files (eg. Jamfile, Jamrules,
> boost-build.jam) as self-contained and as detailed as possible, so a
> new user only needs to look at other documentation if he has special
> needs. 

Great; I can handle that part.

> Basically, include all configuration variable settings that might
> reasonably need to be changed

I don't think we can quite do that, since individual compilers may
need config info, however we can make reference to the toolsets web
pages that document it.

> possibly commented out, and with enough explanation that the user
> could figure out what he needed to change it to,
>
> Daniel Holth just wrote that distutils works for him on Linux
> (apparently he uses Gentoo). He mentioned a Python extension package
> of his called shoutpy which uses boost.python and distutils, and it
> builds on Debian with no problem. Therefore, I might give this a try.
>
> I was wondering why boost.python does not officially support
> distutils. 

Several reasons:

1. When I was investigating distutils, its ability to deal with the
   particular issues of building C++ code was highly/deeply lacking,
   even according to the distutils people.

2. I don't have time to support a great many different build tools.
   Getting portable builds that will work on all the different compilers
   with Boost.Build is hard enough.  If I support bjam and distutils,
   why not make?  Why not scons?  

> If it is for reasons of portability, I think it would do no harm to
> suggest it on the web page as a possible alternative, at least for
> Linux, possibly with a link to shoutpy or some other example of use.

I have no guarantee that it's going to work, and "seems to work for
me" isn't good enough; the build code to support Boost.Python
extensions in all of the different configurations is nontrivial, and
I'd bet you dollars to donuts that a naive build of all the
Boost.Python regression test extensions with distutils will turn up
problems.

HTH,

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com