Re: Writing New Macros

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Eric Blake on 4/10/2007 1:19 PM:
>> calls to the reserved _AC namespace would appear in
>> these custom macros.  Nothing wrong with that right?  :P
> 
> There is indeed something wrong with it.  What does it take to convince
> people that by using undocumented interfaces from reserved namespaces that
> they are setting themselves up for hard-to-debug failures in the future
> when the undocumented interface goes away or slightly changes in
> semantics, as is the right of the package maintainers by the very nature
> that they chose not to document it?  If you really need the functionality,
> and a documented API doesn't provide it, then write a bug report against
> autoconf suggesting that a public API be provided that does the same
> thing, and the testsuite augmented to guarantee stability of the
> interface.  The moral of the story is:
> 
> _Don't use macros in the _AC* namespace if you are not writing a patch for
> Autoconf itself!!!_

It was pointed out to me off-list that my remarks may have come across to
other people with a harsher tone than I intended.  My intent here is not
to forbid you or anyone else from using undocumented macros (after all,
this is open source software, so they are in a sense documented by looking
at the implementation, and the GPL guarantees you the right to use
autoconf, including the undocumented portions, as you see fit).  Rather,
it is to save you the problems of locking yourself into a particular
version where you will be unable to upgrade without taking the burden on
yourself to figure out where all the undocumented internals changed
between versions.  If you follow the philosophy of sticking with the
well-documented and well-tested interfaces, then you have shifted the
burden away from yourself and on to the autoconf maintainers, making your
job easier, and even making the maintainer's job easier.  Things may still
change with version upgrades, but you then have the NEWS to point you to
those changes, along with an implicit agreement that the maintainers must
be willing to help you sort out the impacts because they were willing to
make the documented change.  Whereas if you use a backdoor, and your code
breaks on upgrade, the maintainers have every right to ignore your pleas
for help (fortunately, you can often find someone willing to help, but
that is a rather weak position to be putting yourself in).

For an example of the pain of undocumented interfaces, a quick look at the
NEWS for 2.61 alongside the mailing list archives during that time, shows
how the maintainers expended a disproportionate amount of time trying to
figure out how to politely handle the wide user base that was using the
undocumented _AC_COMPUTE_INT, particularly when the newly documented
AC_COMPUTE_INT uses different parameters, whereas if users had left
_AC_COMPUTE_INT alone or begged much earlier to make it a public
interface, this could have been a non-issue.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFGHCsi84KuGfSFAYARAhWBAKCwpSubPDqWagEUPy5vaUCmnYS3swCfSoZp
ix3WhQDcJQZvMaUy65yhsuU=
=rJiQ
-----END PGP SIGNATURE-----