On Sun, Mar 31, 2002 at 10:48:33PM -0600, Dave Rolsky wrote:
> At least some of the various targets in the Makefiles produced by the
> newer EU::MM appear to have changed. For example, the test_dynamic target
> has changed quite a bit.
>
> But these bits of text were really part of the public API of the module,
> in that you could always overload the test method in MY::test and tweak
> the output text.
Those bits of text were not part of the public API, they're private
information that has leaked into the Lore surrounding MakeMaker (see
rant below). And lore is not an API, no matter how old it is.
However, people didn't really have much choice.
So... what is it you were doing with the test* methods and how? Let's
see what we can preserve.
The rest below is really just me venting bile.
[Small rant about "backwards compatiblity" wrt MakeMaker]
Most of the documentation of MakeMaker is not really documentation.
It's a translation of the code into English without a really good
understanding of what's supposed to be public and what's not.
Worse, most of the documentation just *begs* for one to dig into the
code and rely on private behavior. For example, 5.6.1's MM_Unix
offers the following explanation of test_via_*:
test (o)
Defines the test targets.
test_via_harness (o)
Helper method to write the test targets
test_via_script (o)
Other helper method for test.
Added to that is the very long list of very old MakeMaker bugs. Some
of these have been around for so long they're practically accepted
behavior. There's something of a Lore surrounding how to get
MakeMaker to work, particularly around things like PREFIX and
INSTALLDIRS which haven't worked properly in years. Most of it is
just "this happens to work". Some of it's even been published in
books!
As such I consider most of the documentation as of 5.6.1 to be a bug.
The documentation of constants is passable, but that of methods,
especially the overridable ones, is really just a tempation to break
encapsulation. Whipping the docs into shape is quite a project and
not one I can do alone.
We certainly can't hang onto all the Dirty Tricks people have used
over the years on MakeMaker, otherwise we may as well just freeze
MakeMaker where it is and work on Module::Build. [1] We can't even
really document what's changed because who knows what people
are relying on?
About all we can do is collect what Lore we can. If it's sensible,
canonize and document it. If not, we come up with a canonical way to
accomplish what the user wants and then document that.
[1] And that doesn't happen until 5.8.1. :)
--
Michael G. Schwern <[EMAIL PROTECTED]> http://www.pobox.com/~schwern/
Perl Quality Assurance <[EMAIL PROTECTED]> Kwalitee Is Job One
Death was thought to be fatal.
-- Craig A. Berry in <a05101002b8165afc6b62@[172.16.52.1]>
