[OpenAFS-devel] Future direction for Autoconf macro handling in OpenAFS

[Jeffrey Hutzelman]

--On Thursday, July 01, 2010 01:43:51 PM -0700 Russ Allbery 
<rra@stanford.edu> wrote:

>> No thanks.  I'd much rather have one "main program" than two, even if
>> that means conditionalizing some things on which configure script we're
>> building, as acinclude.m4 currently does.  I actually believe the
>> current split is close to ideal, with configure{,-libafs}.in containing
>> only the bits that really _need_ to be in the top level, either because
>> autoconf requires that or because not doing so confuses tools.
>
> I think it's confusing to put things into acinclude.m4 that are only used
> by configure.in.  This is unlike the way nearly every other free software
> program using Autoconf uses its configure.ac file and is unnecessarily
> confusing for contributors.

On the contrary, nearly every other free software program using Autoconf 
doesn't use acinclude.m4 *at all*.  The ones that do are usually using it 
as the transitional mechanism it was intended to be, rather than as a way 
of abstracting out common "main" code between multiple configure scripts.

There aren't really many models for how to do what we do, so as long as we 
maintain multiple configure scripts, we're going to have to figure out our 
own way to keep that as painless as possible.  In my mind, that means 
insuring that most people don't have to look at configure.ac or 
configure-libafs.ac, except to discover that everything they care about is 
really in acinclude.m4 (and we should have comments to that effect).  It 
especially means that things like configure options should not be split 
between acinclude.m4 and the true top-level files; they should be in one 
place.

> Of course, *most* of the material in acinclude.m4 should be moved into
> separate macro files in src/cf/*.m4

Well, yes.  Once we've eliminated the spaghetti, what's left of the "main" 
program in acinclude.m4 should end up being a handful of macro calls and 
not a whole lot else.

This probably actually includes lots of command-line options.  As long as 
the information about what command-line options exist is consolidated in 
one place, I think I'm in favor of moving the details into separate macros 
in appropriate src/cf/*.m4 files, in the process bringing an option 
together with the bits that implement its effect.


>> No.  acinclude.m4 should have all of them, and conditionalize which ones
>> are included on OPENAFS_CONFIGURE_LIBAFS.  IMHO this is much more
>> maintainable.
>
> I don't think I agree with the maintainability of this approach.  The
> conditionals make the code harder to read

They don't have to be.

> and conditionals that can be
> avoided by simply putting the code in the correct location in the first
> place should be avoided, IMO.

Often, when the choice is between reducing maintainability by having lots 
of conditionals and reducing maintainability by having related code 
scattered all over the case, another layer of abstraction is called for. :-)


>> I also question the premise that configure-libafs shouldn't at least
>> recognize every --enable switch defined for OpenAFS.  Users shouldn't
>> have to know which switches happen to have an effect on libafs and which
>> don't; configure-libafs should not complain about an "unrecognized"
>> switch that in fact is valid but happens not to affect libafs.  On the
>> other hand, I would be fine with omitting such switches from
>> configure-libafs's help output.
>
> I'm not sure that's even possible.  Autoconf documents HELP-STRING as a
> mandatory argument

Oh, did they finally decide that they know what I'm doing better than I do, 
and I couldn't possibly want to have undocumented options for backward 
compatibility without confusing new users?  That's really unfortunate.

> I don't see any strong reason to avoid
> people getting unrecognized flag warnings when using userspace-only flags
> with configure-libafs.  They're only warnings.

Details like what functionality is implemented in kernel and what parts are 
in afsd or some other component should not be things users need to know 
about.  It's nice to be able to say "they're only warnings", but some 
people like to get rid of warnings, and will blindly do the silliest things 
to do so, especially if management says "there must not be any warnings" 
without also adding any constraints about actual correctness. :-)

Let's not make it so someone who "gets rid of a warning" today ends up 
tomorrow missing a feature, or worse, having incompatible kernel and 
userspace.  If that means configure-libafs includes some options in its 
help that don't do anything, maybe that's OK.



> We could make more progress on getting rid of clutter if we wanted.  None
> of the libafs support files really need to be in the top level directory,
> since they're not invoked from there.  They could be moved elsewhere
> without causing any harm.

As long as we're cleaning things up, then...

We have four or five more README files than we should (README.GIT and 
README.WARNINGS can and should be folded into README.DEVEL, which possibly 
should be moved to the web site.  README-WINDOWS can and should be folded 
into README.  README.PTHREADED_UBIK does not belong in the top level).

We have one more INSTALL file than we should.  The generic instructions are 
not only fairly old, but also contain information that is irrelevant, just 
plain wrong, or even actively harmful.  For example, the discussion of 
system types is pretty much completely wrong; anything we do that is 
system-type-dependent depends on the AFS systype, not the configure one. 
The README file already contains much better installation instructions; we 
should punt the generic GNU one.