config.hpp - improving utility and ease of maintenance

From: John Maddock (John_Maddock_at_[hidden])
Date: 2001-06-01 06:26:43

Vesa's config scheme is very timely: I've been contemplating integrating
the regex config options with config.hpp - some have already been merged,
but others haven't primarily to prevent config.hpp from becoming as
cluttered as  regex_config.hpp.  However, I believe that with a few small
tweaks we can make Vesa's scheme even better:

1) I believe it is vital to separate configuration options into 3 separate
and orthogonal categories: the compiler, the standard library, and the
platform.

Consider that gcc can be used on any of the following platforms:

unix (multiple versions)
Mac OS X
BeOS
Win32

and with the following standard libraries:

libstdc++2
libstdc++3
STLPort
Dinkumware (for Linux)
Object space library

Or that Solaris has a <stdint.h>, no matter whether the compiler is gcc,
Como or Sunpro,

and you should see what I mean.  I admit that there is some tangling here,
but not so much as to make the scheme unworkable.  I use a similar scheme
in the regex headers and it works very well: however it's all in a single
monolithic header, and that makes it very hard to get to grips with for
maintenance, as well as having all the drawbacks that Vesa highlights.

2) We really need a method to regression test the boost configuration - in
fact I think that this should come *before* changes to config.hpp are
committed.  What I would like to see are a set of separate test files, one
for each feature, which will only compile if that feature is supported. 
The feature can then be tested in both a "positive" and a "negative" sense:

Positive test: should not compile if the macro needs to be defined and is
not:

#include <boost/config.hpp>
#ifndef BOOST_MACRONAME
// include test for BOOST_MACRONAME
#include "macroname.cxx"
#endif

Negative test: Will compile only if the macro is defined when it need not
be:

#include <boost/config.hpp>
#ifdef BOOST_MACRONAME
// include test for BOOST_MACRONAME
#include "macroname.cxx"
#else
#error this file should not compile
#endif

Clearly this involves a lot of test files; I do not believe that these
should be a part of the main boost regression tests results - after all the
average end user has no need of this information, and in any case these
tests should require running relatively infrequently (only when a compiler
changes, or a new macro is added).  I'm also hoping that various boosters
have some of these tests as code snippets on their machines already (and
yes that is a hint!), but for those that aren't already available I don't
mind spending some time writing some of these - some help would be welcomed
though.

3) The test files above can also serve as the basis for an autoconf (or
whatever) script if required.  I realize that this proposal is not popular
around here, but it is often asked for - and most Unix heads expect it. 
Whatever this would be left until the end.  One option would be for
autoconf (or whatever) to generate headers that are separate from the main
boost headers, but which can be used as the basis for a new config (rather
like STLPort).

4) I would prefer to see a "tidier" directory structure than the one Vesa
has come up with (echoing Jens' comments), and in fact I believe this is
possible if we change include directories to defines, imagine that
config.hpp looks like this:

//
// define default config headers,
// these dispatch to the real config header automatically:
#ifndef BOOST_COMPILER_CONFIG
#define BOOST_COMPILER_CONFIG <boost/config/compiler.hpp>
#endif
#ifndef BOOST_STDLIB_CONFIG
#define BOOST_STDLIB_CONFIG <boost/config/stdlib.hpp>
#endif
#ifndef BOOST_PLATFORM_CONFIG
#define BOOST_PLATFORM_CONFIG <boost/config/platform.hpp>
#endif

//
// include config headers:
//
#include BOOST_COMPILER_CONFIG
#include BOOST_STDLIB_CONFIG
#include BOOST_PLATFORM_CONFIG

//
// include platform tailoring
// this file serves as a basis for
// autoconf [optional], or for hand
// tailoring to the platform,
// Most (all?) of the options in here should
// be user settings (eg don't give me threading support
// even if it's available), rather than strictly required
// settings.
//
#include <boost/config/site.hpp>
//
// include post config options
// this includes things like BOOST_STATIC_CONSTANT
// and normalisation code (where one macro implies another).
#include <boost/config/suffix.hpp>

Now by default config.hpp will include the dispatching headers
<boost/config/compiler.hpp> etc, which will then dispatch to the actual
config, for example <boost/config/compiler/borland.hpp> if __BORLANDC__ is
defined.  However if you want you could define BOOST_COMPILER_CONIG to
<myheader> and that's what boost will look for.  I believe that this is
actually more versatile that the scheme originally proposed, as well as not
having a directory structure quite so deep.  Note that once set up
<boost/config.hpp> should *never* *ever* change (that means removing
comments and revision history etc to the html documentation).  The
dispatching headers <boost/config/compiler.hpp> etc would change quite
often to begin with, but eventually hardly at all.  Likewise the individual
compiler/platform/library config files <boost/config/stdlib/visualcpp.hpp>,
<boost/config/platform/win32.hpp>, <boost/config/stdlib/stlport.hpp> would
change infrequently (compared to the current config.hpp) once correctly set
up.  The key is that we don't know whether everything is set up correctly
until we have a test suite - I suspect that some regression tests currently
failing to compile are actually config issues.

- John Maddock
http://ourworld.compuserve.com/homepages/john_maddock/