[Pdx-pm] Starting from scratch with Module::Build

[Michael G Schwern]

On Fri, Jul 01, 2005 at 04:12:06PM -0700, Eric Wilhelm wrote:
> >But it talks almost exclusively about the various detailed things you
> > can do in Build.PL and not about basic things like where your modules
> > and tests go.
> 
> Hmm.  Maybe we (them) need a Module::Newbie pod.

The authoring docs need to be finished, for starters.  The original plan
was, I think, to break the docs down into:

Basic module installation
Advanced module installation
Basic module authoring
Advanced module authoring
Extending Module::Build

I've been planning on restructuring MakeMaker's docs along the same lines as 
soon as I get a dump truck of motiviation to do so.


> > I think h2xs has contributed 
> > greatly to the "writing modules is hard" myth.
> 
> I can't find it now, but I distinctly remember reading something like 
> "Always start with h2xs.\n"x3 in some documentation or other (was it in 
> the camel book?)

Those were the first lines of the ExtUtils::MakeMaker "How To Write A 
Makefile.PL" documentation.

     How To Write A Makefile.PL

     The short answer is: Don't.

             Always begin with h2xs.
             Always begin with h2xs!
             ALWAYS BEGIN WITH H2XS!

     even if you're not building around a header file, and even if you don't
     have an XS component.

I blame that for much of the confusion surrounding writing a module for
so long both because it lead the user to view the overly complicated h2xs
templates as being necessary and because it meant the MakeMaker docs never 
felt the need to have a simple Makefile.PL tutorial.

I cleaved it from the docs about two years ago.


-- 
Michael G Schwern     schwern at pobox.com     http://www.pobox.com/~schwern
Reality is that which, when you stop believing in it, doesn't go away.
	-- Phillip K. Dick