Re: [Boost-build] Using bjam in the sandbox

Subject: Re: [Boost-build] Using bjam in the sandbox
From: Edward Diener (eldiener_at_[hidden])
Date: 2009-11-05 11:42:26

Vladimir Prus wrote:
> Edward Diener wrote:
> 
>> Vladimir Prus wrote:
>>> On Sunday 01 November 2009 Edward Diener wrote:
>>>
>>>>>> What is the reason fo the error message ?
>>>>> Boost.Jam -- which is the low-level build engine -- has to locate
>>>>> Boost.Build -- which is the real build system. For that purpose, it searches
>>>>> for a file named 'boost-build.jam' that should contain directives where
>>>>> to search for Boost.Build. That 'boost-build ;' means to consult
>>>>> environment variable called 'BOOST_BUILD_PATH', which is probably
>>>>> not set, and usually is not required -- since boost-build.jam in Boost
>>>>> root contains direct path to Boost.Build.
>>>> I set the BOOST_ROOT environment variable, bu it still did not work.
>>> I have looked into that more, and it appears that:
>>>
>>> 1. The library setup needs some love. In particular, it uses non-standard
>>> variable names for everything.
>>>
>>> 2. It does not actually have any BoostBook docs, only doxygen -- buildable
>>> by running doxygen directly.
>>>
>>> Before I go on fixing (1), can you clarify the point (2) -- that is, what
>>> docs are you planning to build. If you're building docs for some other
>>> library, can you let me know which one, so that I can check it?

I do not see it as your responsibility to fix a sandbox library's .bjam 
file unless you are the one who created it originally. My basic concern 
is that a user of Boost build can understand what is happening when bjam 
is run, from the output that is generated.

>> I went to John Torjo's logging implementation in the sandbox and
>> attempted to run bjam there. Subsequently I saw a
>> 'generating_the_docs.txt' file in that directory which says how to
>> manually build the documentation using doxygen.
>>
>> Nonetheless I am more concerned about the ease by which a user of
>> Boost.Build can understand what is wrong than this particular situation.
>> For instance the error message says:
>>
>> "Unable to load Boost.Build: could not find build system.
>> ---------------------------------------------------------
>> C:\Programming\VersionControl\sandbox\logging\boost-build.jam attempted
>> to load
>> the build system by invoking
>>
>>     'boost-build ;'
>>
>> but we were unable to find "bootstrap.jam" in the specified directory
>>
> 
> Are you sure there's no extra line printed right after that? Not that
> it would help very much, but still.
> 
>> Please consult the documentation at 'http://www.boost.org'."
>>
>> How is the user of bjam supposed to solve the problem based on this
>> error message ? 
> 
> I agree that the error message is not exactly clear. Nor is the link
> direct enough.
> 
> At present I recommend you to
> 
> - set environment variable BOOST_BUILD_PATH to <boost-root>/tools/build/v2
> - set environment variable BOOST_ROOT to <boost-root>
> - let me know if any sandbox library fails to work with those settings. I'll
> fix logging shortly.

I set both BOOST_BUILD_PATH and BOOST_ROOT and tried bjam in the sandbox 
logging directory. I no longer get any errors. My output is now:

"warning: No toolsets are configured.
warning: Configuring default toolset "msvc".
warning: If the default is wrong, your build may not work correctly.
warning: Use the "toolset=xxxxx" option to override our guess.
warning: For more configuration options, please consult
warning: 
http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html

...found 1 target..."

I am glad it is no longer giving me errors but that last line is not 
very informative either. What target has been found ? Has anything been 
built ? This is the sort of thing that always bothers me about using 
bjam. I think the output needs to be informative enough to tell the user 
what has happened.

> 
> For future, what would you say about the following wording:
> 
>         Boost.Build could not be located.
> 
>         The Boost.Build startup module, 'bootstrap.jam', could not be found.
>         The search was performed in:
> 
>         - Directories given by the BOOST_BUILD_PATH environment variable:
>           - currently none
>         - In the directory of bjam.exe:
>           - c:/something/
> 
>         Please see <direct link to reference> for further details. 
> 
> Note that this is not a wording change only -- it depends on some behaviour
> changes to be done first.

The above is much more informative.

> 
>> In particular, is there some Boost.Build documentation 
>> which explains how .bjam files are found ? I do not see this as a topic
>> heading anywhere in the Boost.Build v2 documentation.
> 
> Does http://tinyurl.com/ybocjzv answer your questions? (This link is outside
> Boost, since there are some site problems, that should resolve in 24 hours)

Yes, that explains it well. But should not there be docs on how .bjam 
files are found in general ? Does all finding of .bjam files follow the 
same rules as explained in that link, ie. up the file hierarchy and then 
in the directories of BOOST_BUILD_PATH ? If not, then you should explain 
how .bjam search actually works. In either case it would be welcome if 
there were a general topic in the Boost Build doc of how Boost Build 
finds .bjam files.