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

[Faheem Mitha]

Hi, 

Thanks very much for the followup.

On Sun, 11 Apr 2004 07:56:43 -0400, David Abrahams
<dave at boost-consulting.com> wrote:

> [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.

What I meant is that an installation of the Boost build system is
required. Therefore the bjam executable requires more than just itself
and the local config files referring specifically to that extension
(eg. Jamfile, boost-build.jam) in order to build.

>> 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.

Ok. Looks like I will be filing a bug report. libboost-dev looks like
a reasonable starting point. Any comments from other Debian users
here? Is all this already supplied in Debian and I am not aware of it
somehow?

>> 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.

Ok.

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

Ok

>> 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.

Well, perhaps error is the wrong word. However, before I can file a
bug report, I do need to know whether these are the *only* files
required for an extension build. See below.

>>> 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?

I think the tutorial would be a good place to say something about
this. Bear in mind that most people will pass that way at least at the
beginning, and at least some of them will not be familiar with the
boost build system.

>> If these tools/build/v1 should be part of a binary installation,
>> please 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.

Well, to clarify, I mean you should be able (at least for a modern
Linux distribution) to install packages (using rpm, apt, emerge
whatever) all necessary files into the system to enable such
extensions to build. The word binary may be misleading in this
context.

Is it correct to say that the files in build/v1 would be enough by
themselves for the extension to build against? That is my impression,
since boost-build.jam in the libs/python/example directory is pointing
to it, and nothing else is the build process is looking for other
files in the Boost installation.

However, it seems possible, since compilation took so long, that the
build also compiled files elsewhere in the sources as part of the
extension build. If so, this would make things more difficult. I'd
appreciate information about this.

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

Surely a complete source copy is not necessary if only certain files
are required.

>> 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?

Again, the tutorial would be a good place.

>> 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.

In Jamrules, mention

path-global PYTHON_ROOT : /usr ;
path-global PYTHON_VERSION : 2.3 ;

at least, these will frequently need to be changed.

Possibly also add a line for 

$(ALL_LOCATE_TARGET)

since people often want to control where their built binaries will end
up. I know I do.

None of these are compiler/tool-chain dependent config options, as far
as I can see.

You already mention python config stuff in Jamrules (in
libs/python/example/Jamrules), but put in the actual lines to be used
so people don't have figure out the exact syntax.

>> 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?  

Well, distutils is the official build tool for Python extensions, as I
understand it. So it is not quite the same as make or scons etc.

A few questions.

* Is work underway to add the necessary C++ support to distutils?

* Once there is sufficient support, would you consider officially
supporting distutils?

* Is there anything you can point me to which discusses distutil's
deficiencies wrt to C++?

I think I will continue using distutils for the moment, at least till
such time as I run into problems. I suspect for the rather simple C++c
code I am likely to write, I will be Ok.

>> 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.

Ok. Fair enough.

Thanks for the detailed replies.

                                                           Faheem.