NAME
    Dpchrist::ExtUtils::MakeMaker - additional Makefile targets and rules

SYNOPSIS
        eval {
            require Dpchrist::ExtUtils::MakeMaker;
            import  Dpchrist::ExtUtils::MakeMaker (
                mcpani   => $ENV{CPAN_AUTHORID},
                pod2html => 'lib/Dpchrist/ExtUtils/MakeMaker.pm',
                readme   => 'lib/Dpchrist/ExtUtils/MakeMaker.pm',
                release  => $ENV{RELEASE_ROOT},
            );
        };
        warn $@ if $@;

    eval(), 'require', and import() are preferred to 'use' so that 'perl
    Makefile.PL' will work on systems that don't have this module installed.

DESCRIPTION
    This documentation describes module revision $Revision: 1.4 $.

    This is alpha test level software and may change or disappear at any
    time.

    This module contains override routines for ExtUtils::MakeMaker which add
    optional rules and/or targets to the Makefile generated by
    WriteMakefile().

  CLASS METHODS
   import
        # Makefile.PL
        eval {
            require Dpchrist::ExtUtils::MakeMaker;
            import Dpchrist::ExtUtils::MakeMaker (
                [TARGET => ARG,]...
            );
        };
        warn $@ if $@;

    Daisy-chains this module's MY::postamble() override into
    ExtUtils::MakeMaker for the given Make TARGET. One or more TARGET => ARG
    pairs may be given.

    Available Make targets are as follows:

   mcpani
        mcpani => AUTHORID,

    Adds a Make target 'mcpani' to the Makefile generated by
    ExtUtils::MakeMaker::WriteMakefile() which adds the distribution tarball
    to the MCPAN working directory (repository) and pushes it to the MCPAN
    local directory when the following commands are issued:

        $ make dist
        $ make mcpani

    Note that you need to run 'make dist' to create the distribution tarball
    before running 'make mcpani'.

    AUTHORID is used for the --authorid parameter to 'mcpani'. Default is
    'NONE'. I put my CPAN author id (DPCHRIST) into an environment variable
    CPAN_AUTHORID in my .bash_profile:

        # .bash_profile
        export CPAN_AUTHORID=DPCHRIST

    I then use this environment variable in Makefile.PL:

        # Makefile.PL
        mcpani => $ENV{CPAN_AUTHORID},

    You will need a working CPAN::Module::Inject installation before running
    'make mcpani'. See the following for details:

        perldoc mcpani
        http://www.ddj.com/web-development/184416190
        http://www.stonehenge.com/merlyn/LinuxMag/col42.html

    I set an environment variable in .bash_profile that points to my mcpani
    configuration file:

        # .bash_profile
        export MCPANI_CONFIG=$HOME/.mcpanirc

    Here is my mcpani configuration file:

        # .mcpanirc
        local: /mnt/z/mirror/MCPAN
        remote: ftp://ftp.cpan.org/pub/CPAN ftp://ftp.kernel.org/pub/CPAN
        repository: /home/dpchrist/.mcpani
        passive: yes
        dirmode: 0755

    My staging directory is ~/.mcpani.

    /mnt/z/mirror/MCPAN is directory on my web server that is served as
    http://mirror.holgerdanske.com/MCPAN/.

    I can then run cpan on my machines and have them use the web mirror to
    fetch my modules (I only needed to do this once):

        $ sudo cpan
        cpan[1]> o conf urllist http://mirror.holgerdanske.com/MCPAN/
        cpan[2]> o conf commit
        cpan[3]> reload index

    Whenever I inject a new or updated module, I need to reload the cpan
    index before I install the module:

        $ sudo cpan
        cpan[1]> reload index
        cpan[2]> install MyModule

   pod2html
        pod2html => [ LIST ],

    Adds a rule to the Make target 'all' in the Makefile generated by
    ExtUtils::MakeMaker::WriteMakefile() which will run 'pod2html' against
    the files in LIST (e.g. Perl modules and scripts) using the commands:

        pod2html FILE > PACKAGE-VERSION.html
        rm -f pod2htm?.tmp

    PACKAGE and VERSION are determined by reading FILE:

    * The namespace of the first 'package' decalaration found is used for
    PACKAGE. If no 'package' declaration is found,
    File::Basename::basename(FILE) is used for PACKAGE.

    * The argument of the first '$VERSION' variable assignment found is
    evaluated and used for VERSION.

    HTML files will be generated or updated whenever the following commands
    are issued:

        $ make

    Or,

        $ make all

    If there is only one FILE, it may be given as the argument to import():

        pod2html => FILE,

   readme
        readme => FILE,

    Adds a rule to the Make target 'all' in the Makefile generated by
    ExtUtils::MakeMaker::WriteMakefile() which will run 'pod2text' against
    FILE (e.g. Perl module) using the command:

        pod2text FILE > README

    The README file will be generated or updated whenever the following
    commands are issued:

        $ make

    Or,

        $ make all

   release
        release => RELEASE_ROOT,

    Adds a Make target 'release' to the Makefile generated by
    ExtUtils::MakeMaker::WriteMakefile() which copies all *.tar.gz and
    *.html files to a subdirectory under RELEASE_ROOT that is named after
    the module (changing double colons to a single dash) when the following
    commands are issued:

        $ make dist
        $ make release

    Note that you should run 'make dist' to create the distribution tarball
    before running 'make mcpani'.

    I set an environment variable in my .bash_profile:

        # .bash_profile
        export RELEASE_ROOT=/mnt/z/data/release

    and use this environment variable in Makefile.PL:

        # Makefile.PL
        release => $ENV{RELEASE_ROOT},

  EXPORT
    None.

INSTALLATION
    Old school:

        $ perl Makefile.PL
        $ make
        $ make test
        $ make install

    Minimal:

        $ cpan Dpchrist::ExtUtils::MakeMaker

    Complete:

        $ cpan Bundle::Dpchrist

    The following warnings should not prevent installation:

        Can't locate Dpchrist/ExtUtils/MakeMaker.pm in @INC (@INC contains: 
        /etc/perl /usr/local/lib/perl/5.10.0 /usr/local/share/perl/5.10.0 /u
        sr/lib/perl5 /usr/share/perl5 /usr/lib/perl/5.10 /usr/share/perl/5.1
        0 /usr/local/lib/site_perl .) at Makefile.PL line XX.

        Can't locate Test/Manifest.pm in @INC (@INC contains: /etc/perl /usr
        /local/lib/perl/5.10.0 /usr/local/share/perl/5.10.0 /usr/lib/perl5 /
        usr/share/perl5 /usr/lib/perl/5.10 /usr/share/perl/5.10 /usr/local/l
        ib/site_perl .) at (eval X) line XX.
        BEGIN failed--compilation aborted at (eval X) line XX.

  PREREQUISITES
    See Makefile.PL in the source distribution root directory.

SEE ALSO
        mcpani
        pod2text
        pod2html
        ExtUtils::MakeMaker
        ExtUtils::MM_Unix
        Programming Perl, 3 e., Ch. 29 "use" (pp. 822-823).
        Mastering Perl, Ch 10 "Replacing Module Parts" (pp. 160-162).

AUTHOR
    David Paul Christensen dpchrist@holgerdanske.com

COPYRIGHT AND LICENSE
    Copyright 2010 by David Paul Christensen dpchrist@holgerdanske.com

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; version 2.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

