README for Module::Husbandry

   ALPHA CODE ALERT: This code is alpha; the API and behaviors are
   likely to change.  This release is for evaluation and feedback;
   see the TODO file for some ideas of where this might go.

A module and a set of wrapper scripts that let me manage perl
distributions a bit more easily.  There are more to come; the current
crop is:

   newpmdist      Creates a new distribution tree and populates it
   newpm          Creates a new module in a distribution
   mvpm           Renames a module and all occurences of its module name
                  and path:

                      s{Foo::Bar}{Foo::Bat}g;
                      s{lib/Foo/Bar.pm}{lib/Foo/Bat.pm}g;
                      s{t/Foo-Bar.t}{t/Foo-Bat.t}g;

To use the new* scripts, you need a ~/.newpm/ directory with appropriate
templates (see below).  mvpm just makes some rash assumptions (also see
below) about your directory structure and test script naming convention.

Here are the usages:

   newpmdist Foo-Bar    ## Create Foo-Bar/ and populate it
   newpmdist Foo::Bar   ## as above


   newpm Foo::Bar           ## Create lib/Foo/Bar.pm and t/Foo-Bar.t
   newpm lib/Foo/Bar.pm     ## Create lib/Foo/Bar.pm and t/Foo-Bar.t
   newpm lib/Foo/Bar.pod    ## Create lib/Foo/Bar.pod only

   newpm Foo::Bar Foo::Bar  ## as above, but for multiple modules


   mvpm From::Module       To::Module        # Use module names
   mvpm lib/From/Module.pm lib/To/Module.pm  # or paths from main project dir
   mvpm lib/From/Module.pm To::Module        # or mix and match

   mvpm -r From            To                # move dir tree (TODO)
   mvpm -r lib/From        lib/To            # move dir tree (TODO)

As you can see, each can take a module name, if that's the way you
work, or a file or directory name.  Using file or directory names lets
you take advantage of your shell's autocompletion and history features.
For instance:

   $ newpm lib/Fundingulus/Maximus.pm
   $ edit !$

can be typed in a lot fewer keystrokes than

   $ newpm Fundingulus::Maximus
   $ edit lib/Fundingulus/Maximus.pm

newpmdist and newpm use a set of templates to instantiate new files.
These are stored (for now) in ~/.newpm:

   $ cd ~/.newpm && find .
   .
   ./Template.t
   ./Template.pm
   ./skel
   ./skel/MANIFEST.SKIP
   ./skel/Makefile.PL
   ./skel/t
   ./skel/CHANGES

This means that you control what files are populated how.  Some
example files (those) are in newpm_example_dir/ in the source tarball.

ASSumptions
===========

These tools make the assumption that you use a working directory
structure like:

   Foo-Bar/
       lib/
           Foo/
               Bar.pm
               Bah.pm
               Bat.pm
           Zed.pm
       t/...

and not the Foo-Bar/Bar.pm style promulgates by h2xs.  This layout
(storing all .pm and .pod files under lib/) is more consistent and
flexible than storing the .pm and .pod files in the main directory,
but may not be to your liking.  Patches welcome :).

One side effect of this is that XS modules are may not be
well supported.

newpm and mvpm also create and check for test suites named after the
module like so:

   Foo       t/Foo.t
   Foo::Bar  t/Foo-Bar.t

 This is also arbitrary, and even I don't really like it that
much, but it's the easiest way I could think of to be able to make
and rename test files automatically.


Example
=======

Here's an example newpmdist invocation.  Towards the end, newpmdist
also does a newpm, so you can get a feel for what that's like (all lines
but the first are emitted by newpmdist):

   $ newpmdist Foo-Bar
   newpmdist$ mkdir -p Foo-Bar
   newpmdist$ chdir Foo-Bar
   newpmdist$ install Makefile.PL
   newpmdist$ install MANIFEST.SKIP
   newpmdist$ install CHANGES
   newpmdist$ install lib/Foo/Bar.pm
   newpmdist$ mkdir -p lib/Foo
   newpmdist$ install t/Foo-Bar.t
   newpmdist$ mkdir -p t
   newpmdist/usr/local/bin/perl Makefile
   Checking if your kit is complete...
   Looks good
   Writing Makefile for Foo::Bar
   newpmdist$ chdir ..

Here's what things look like after all that:

   $ cd Foo-Bar
   $ find .
   .
   ./Makefile.PL
   ./MANIFEST
   ./MANIFEST.SKIP
   ./CHANGES
   ./lib
   ./lib/Foo
   ./lib/Foo/Bar.pm
   ./t
   ./t/Foo-Bar.t
   ./Makefile
   $ perl Makefile.PL
   Writing Makefile for Foo::Bar
   $ make distcheck
   /usr/local/bin/perl "-MExtUtils::Manifest=fullcheck" -e fullcheck
   $ make test
   cp lib/Foo/Bar.pm blib/lib/Foo/Bar.pm
   PERL_DL_NONLAZY=1 /usr/local/bin/perl "-MExtUtils::Command::MM" "-e" "test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
   t/Foo-Bar....ok
   All tests successful.
   Files=1, Tests=1,  0 wallclock secs ( 0.06 cusr +  0.00 csys =  0.06 CPU)

The module Module::Husbandry uses lazy loading of required modules to
minimize running time.