Currently the C++ distribution tarball is not "pure source", as it contains
generated source and documentation files that are pre-generated while building
the distribution. This is bad (see below for details of why.) I'd like to move
towards a pure-source distribution, proposal below.
== Why the current situation is bad
- In a normal project "make dist" is quick - it basically just creates a
tarball. In qpid "make dist" is slow - it does an entire build because needs
qpidd in order to generate the man page from qpidd --help.
- "make distcheck" takes twice as long as it should because it does *two*
builds, first to generate the man page, then to build the real distro.
- "make distcheck" and VPATH builds are frequently broken (I think both are
broken right now) because of confusion over whether generate sourced code is in
"srcdir" or "builddir". It should be in builddir when building from scratch, but
inevitably ends up in srcdir in a distro tarball. Getting the build system to
work properly in both scenarios is tricky.
The results of all the above is that people avoid building distros like the
plague because it's slow and likely to fail, and therefore we get very little
testing of the distro-buildingn process.
== Why did I get us into this mess in the first place?
There was a desire to let people build the distro without having all of the
dependencies required to build generated source & docs. At the time, the code
generator was in Java, which is a totally unacceptable dependency for a C or C++
project, so this was probably the right thing to do. That is no longer the case
- the current generator is in ruby - so I don't think the original reasoning holds.
I'd like to go towards a pure source distribution, with ruby as a requirement to
build. I'd like to make some other requirements optional, i.e. if present they
add functionality but you can do a basic build without them:
- python: run python test suite if present.
- doxygen: generate API doc if present.
- graphviz: add class diagrams to API doc if present
- help2man: generate man page if present.
I think this gives us a reasonable minimal requirement set (only adding ruby)
and provides flexibility to do a basic build without all the doc tools. We can
provide generated documentation on the project web pages for people who
cant/dont want to build it themselves.
Any objections?
