Boost logo

Boost-Build :

From: Beman Dawes (bdawes_at_[hidden])
Date: 2008-08-20 11:23:37

Vladimir Prus wrote:
> Beman Dawes wrote:
>> I've just created ticket #2232. See below.
>> This is a very high priority issue; it has already cost Daniel and me a
>> great deal of trouble. I suspect it may be the cause of several trouble
>> reports from other Boost developers where one developer gets different
>> results from another developer.
>> Who is willing to work on it? Neither Daniel or I know enough about jam
>> files to tackle it.
>> --Beman
>> ---------------
>> Building documentation requires a lengthy tool chain to work correctly.
>> The following tools have to be installed:
>> libxml2, libxslt, doxygen, docbook-xml42, docbook-xsl, tetex (?),
>> ghostscript
> This list seems fairly strange to me:
> - How comes we depend on tetex? And ghostscript? Is this always necessary
> for building docs, or just for maintaining some files that are subsequently
> included into final docs? If the latter, then it's not our problem. If the
> former, then how comes?

IIRC, that additional dependency was introduced to support
Boost.Accumulators. Perhaps Eric could comment?

> - libxml2 and libxslt are libraries, whereas we only need a binary called
> xstlproc. How that binary works is an implementation detail of that library.

I got the list from

If that list is wrong, you need to work with Daniel James to correct it.

>> user-config.jam needs to supply usings for:
>> xsltproc, boostbook with docbook-xsl and docbook/4.2, doxygen,
>> quickbook
>> Experience has shown that (1) even very experienced Boost developers can
>> have missing tool chain items,
> Note that quickbook needs no specific configuration; it's built from source
> if necessary. Which leaves xstlproc, boostbook/docbook and doxygen as things
> that must be configured.

That list also came from

Again, if it is wrong for any platforms, it needs to be corrected.

>> and (2) missing tool chain items are very
>> difficult to diagnose and repair because the current bjam setup does not
>> issue meaningful error messages, produces partial documentation, and
>> gives the appearance of working.
>> The requested fix is twofold:
>> * Specific error messages should be issued if the tool chain is not
>> complete. The messages should distinguish between tools not being
>> installed and user-config.jam not having all the required entires. The
>> error messages should name the specific missing tool or missing
>> user-config.jam entry.
> Do you want those checks to be done even when not building docs?

Only when building docs. Better yet, only for the specific docs being built.

>> * If one of the above errors is detected, the process should stop at
>> that point. Currently partial documentation is built, and that can be
>> very misleading and time-consuming. If the tool chain is wrong, nothing
>> at all should be built.
> Can you explain how exactly can I get "partial documentation" built?

1) Temporarily rename /usr/share/docbook-xsl and
/usr/share/xml/docbook/4.2 something else so they won't be found.

2) On a recent trunk checkout, delete bin.v2 and libs/mpi/doc/html if
they exist.

3) cd boost-root/libs/mpi/doc
    bjam >log

4) Note that while boost-root/libs/mpi/doc/html was created, it doesn't
contain anything.

5) Note that log doesn't clearly identify the missing component, or even
clearly say that there was a serious problem.

> For
> example, if I omit "using doxygen" I get hard error immediately. Also,
> commenting out "using boostbook" gives me a hard error as well.

Hum... I tried that for libs/mpi/doc and got no error, and no
documentation generated, either.


Boost-Build list run by bdawes at, david.abrahams at, gregod at, cpdaniel at, john at