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

[Faheem Mitha]

On Mon, 12 Apr 2004 14:51:02 -0400, David Abrahams
<dave at boost-consulting.com> wrote:

> Faheem Mitha <faheem at email.unc.edu> writes:
>
>>>> 1) Please clarify which files correspond to the boost build system. 
>>>
>>> Where should that be clarified?
>>
>> I think the tutorial 
>
> The Boost.Python tutorial or the Boost.Build tutorial?

I was thinking of the Boost Python tutorial, but looking at it, it
seems the natural place to put information like this is
http://www.boost.org/libs/python/doc/building.html#building_ext

After the line "You are likely to run into compilation or linking
problems otherwise." I suggest adding a para saying

"The files required for a Boost.Python module extension build using
bjam are in boost/python subdirectory of your sources, elsewhere
referred to the root directory of the Boost installation, the files in
the tools/build/v1 of the sources, and the `local' files Jamfile,
Jamrules, and boost_build.jam."

In the line following

"so that the path refers to the tools/build/v1 subdirectory of your
Boost installation."

I suggest adding something like

"This directory contains the files of the Boost.Build system that are
necessary to configure your build environment. Therefore your
extension module build process needs to know where these files are
located.

The `v1' refers to Boost.Build version 1. Version 2 is pre-release and
currently not ready for general use."

Also, in the "Lets Jam!" section of
http://www.boost.org/libs/python/doc/tutorial/doc/building_hello_world.html,
I'd use the Jamfile in
http://boost-consulting.com/boost/libs/python/example/Jamrules, which
I think has the right idea. Is this supposed to be replacing the
version in http://www.boost.org/libs/python/example/Jamrules? I'd also
use it to replace the Jamfile in the tutorial example.

The tutorial is the most important, 'cause that is where people will
start.

>> 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 you could specifically point to a place to add text, and perhaps
> suggest the text, that'd be a big help.

See above.

>>>> 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.
>
> In theory you don't need Boost.Build for that, just like you don't
> need any particular build system to put together a program that uses,
> say, Qt... or Python.  For many Python extension applications, having
> distutils helps.  Likewise, Boost.Build helps.  A lot.

True. Other build methods are possible. However, you do not support
them, and your documentation does not say how to use them. Also, you
say earlier in this thread

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

Also someone said earlier in the thread that executables using
Boost.Build are smaller than those using distutils (got to see that
for myself).

Therefore, users of Boost.Python should have the option of using
Boost.Build and bjam if their other build methods fail them for some
reason, and furthermore it should be made as easy as reasonably
possible for them to do so.

Modern linux distributions break thing up into small pieces with
dependencies between them because they have to. If every build system
required downloading source trees to build against there would be
chaos (no offense intended). I'm not suggesting you support these
efforts of course, but it is reasonable to cooperate with them to the
extent possible.

Debian is my OS of choice, so I am interested in seeing this
functionality properly supported there at least.

Also, I assume you'd like developers to use your software and perhaps
give something back. A lot of developers use Debian, and it would not
hurt to make things easier for them.

In any case, Boost.Python seems a fine tool, and it would be great to
see more people using it.

>> 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.
>
> I don't know what other files may be missing from the Boost tree in
> your distro, so I can't rightly say.  That said, yes, tools/build/v1
> contains all the build system files needed for Boost.Build v1.

There are no files missing from the Debianized Boost sources. Debian
just patches the pristine Boost sources, and the patch does not remove
any of those files.

>> 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. 
>
> I don't know what you mean.  It's very likely to have compiled the
> Boost.Python library out of sources in the libs/python/src directory.

I meant that building (say) a hello world extension should not involve
compiling anything else but the corresponding hello.cpp (in an already
built Boost installation).

>> If so, this would make things more difficult. I'd appreciate
>> information about this.
>
> Keep in mind that Boost is designed to be delivered as a complete
> tree.  You can download a copy from our site or browse the current CVS
> state at http://www.boost-consulting.com/boost.  Packagers that split
> it up in various ways may be leaving out pieces.

True. Care is needed in order for this not to happen.

>>>> 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.
>
> Not neccessarily neccessary, but we're not trying to figure out which
> parts you need and which you don't.
>
>>>> 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.
>
> More specifics please.

See above.

>>> 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 ;
>
> http://boost-consulting.com/boost/libs/python/example/Jamrules
> OK?

Looks good. However

"...(the one containing a subdirectory called "boost/" and a
sub-subdirectory "boost/python/" that contains .hpp files."

needs a closing bracket.

>> 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.
>
> Sheesh, OK.  This is beginning to turn into a mini Boost.Build
> tutorial.

Think of it as a building Boost.Python extensions tutorial. :-)

>> 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.
>
> But people will have to put in different values.

True, but actual examples are always more helpful. You could just
leave them commented out, to make it clear they are intended as
examples. For example, if you put /usr/local, it tells at least Unix
people more (at least me) than "path to root directory of your Python
installation". Actually, I'd put in both, a description and a
commented out value.

>> 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.
>
> make is the official build tool for RedHat systems.

I don't think that a Linux distribution is going to support building
Boost.Python extensions using make. If people have questions, they
will email the relevant free software project's mailing list as I am
doing now, not a RedHat mailing list (or whatever). So why is it
relevant what RedHat (or Debian or Gentoo...) think is the official
build tool?

The point I was trying to make is that Python uses distutils as their
extension build tool of choice, so it is supported, in the sense that
people can write to the relevant python mailing lists and ask for
help. So it is a more obvious choice for Boost.Python extensions
(since they are also python extensions) to standardize on than make or
scons, which have nothing to do with Python per se.

Ok, what I am now going to do is

1) Try moving the /tools/build/v1 directory out of the sources and
seeing whether I can still build a hello world extension.

2) File a bug report with Debian suggesting they create a package in
which to put the necessary /tools/build/v1 files so people can build
Boost.Python extensions against them using bjam. I think
boost-build-files would be a reasonable name.

                                                               Faheem.