From: Stefan Seefeld (seefeld_at_[hidden])
Date: 2008-08-20 08:52:11
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.
> 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 (?),
You are missing python-docutils, which is required for rst
(ReStructuredText) processing. (This one has a separate issue, as it
currently is misconfigured and results in a quite misleading error.)
In any case, I fully agree that the current state is a pita. Having this
long a prerequisite list is bad.
> user-config.jam needs to supply usings for:
> xsltproc, boostbook with docbook-xsl and docbook/4.2, doxygen,
> Experience has shown that (1) even very experienced Boost developers
> can have missing tool chain items, 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.
At what point should this validation be done ? Given how heterogenous
the projects are in terms of doc generation, I would hope that these
checks are target-dependent, i.e. that I don't need to set up tetex if
the project I'm working on doesn't require it.
> * 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.
I would suggest that there is a build target that generates some form of
source tarball, which includes some preprocessed stuff, such as built
documentation. These source packages then only have a limited set of
prerequisites, and would be used for testing.
Only those who run the 'generate-source-tarball' target would need the
doc 'toolchains' (but not the compilers, for example).
Isn't that a useful division of concern & labour ?
-- ...ich hab' noch einen Koffer in Berlin...
Boost-Build list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk