While preparing a revision of the sections in `Installing GCC' relevant
to my platforms, I've just read it front-to-back and found a couple of
problems I'd like to discuss before starting to develop patches.
* As a general note, many sections describe mechanism (which configure
options are available, often without sufficiently describing what they
do in terms someone not developing compilers can understand), but
completely lack guidance about their use, i.e. when to use them and
with which consequences. My favorite examples here were
--enable-threads=solaris, which led some users to configure this way,
not recognizing that the default (posix) was a much better choice, and
--enable-shared (no description what the consequences of disabling
libgcc_s.so.1 are).
* The list of configure options lacks a recognizable structure, which
makes it difficult even for a developer to find out where best to
describe a new one. (The worst offender I've found is the desciption
of --with-libelf and --enable-gold in the list of general libjava
options.) I don't yet have a proposal how to fix this, but will
investigate. There are very different levels of detail, going as low
as setting defaults for specific switches for a particular CPU
(--with-llsc). Add in the problem from the last point (no guidance),
and the installation guide becomes hard to impossible to use for mere
mortals.
I can't help but get the impression that there are far too many
configure options to be useful.
* The guide is far from complete: e.g., the libstdc++ configure options
are missing completely (they are documented in the XML/HTML manual,
but there's not even a pointer to that in the installation guide). I
fear other libraries have similar problems: I've already printed the
output of configure --help for all in-tree configure scripts and plan
to check them against the installation guide. On the other hand,
options described in the installation guide are missing from configure
--help (again, --with-llsc is an example).
* There are tons of markup problems, some of which may be more visible
in the printed version (which I've used for the review).
Specificially,
** it is completely missing in many places,
** it is highly inconsistent, like commands write with and without
quotes, same for target triplets.
I know much of this issue is nitpicking, but such attention to detail
makes for the difference between a quick hack and a polished product.
* It's unclear if we want to keep anything from `Old installation
documentation'. This should be decided once and for all and then
either incorporated into the guide proper or dropped completely.
I don't want this to be merely a rant, so I plan next to revise the
specific instructions for my targets and then try and come up with a
suggestion for a clearer structure for the configuration chapter, though
I fear that much of this will be 4.6 material. After asking for more
guidance on the markup problems, I'll probably come up with a series of
patches making the guide consistent in a particular regard.
Comments?
Rainer
--
-----------------------------------------------------------------------------
Rainer Orth, Center for Biotechnology, Bielefeld University
