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

SYNOPSIS
        # Makefile.PL

        package Dpchrist::ExtUtils::MakeMaker;      # for symbols

        use ExtUtils::MakeMaker;

        eval {
            require Dpchrist::ExtUtils::MakeMaker;
            die 'Skipping Dpchrist::ExtUtils::MakeMaker'
                unless 1.013 <= $Dpchrist::ExtUtils::MakeMaker::VERSION;
            import Dpchrist::ExtUtils::MakeMaker (
                postamble => sub {
                    my ($o, $prev) = @_;
                    return join('',
                        $prev,
                        mcpani  ($o, $ENV{CPAN_AUTHORID}),
                        pod2html($o, 'lib/Dpchrist/ExtUtils/MakeMaker.pm'),
                        readme  ($o, 'lib/Dpchrist/ExtUtils/MakeMaker.pm'),
                        release ($o, $ENV{RELEASE_ROOT}),
                    );
                },
            );
        };
        warn $@ if $@;

        WriteMakefile(
            # ...
        );

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

    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
        import Dpchrist::ExtUtils::MakeMaker (
            SECTION => CODEREF,
            SECTION => CODEREF,
            SECTION => CODEREF,
        );

    Daisy-chains subroutine CODEREF into the Makefile override for given
    SECTION. Any previous override function (e.g. &MY::SECTION) will be
    called before CODEREF and it's output passed as the first argument to
    CODEREF. CODEREF should return a scalar string containing the net text
    to be placed in the appropriate Makefile section.

  OVERRIDE SUBROUTINES
   mcpani
        my $frag = mcpani(OBJECT, AUTHORID);

    Returns Makefile fragment for target 'mcpani' 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'.

    OBJECT is the object provided by ExtUtils::MakeMaker internals.

    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
        my $frag = pod2html(OBJECT, LIST);

    Returns Makefile fragment for target 'all' 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.

    OBJECT is the object provided by ExtUtils::MakeMaker internals.

    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
        my $frag = readme(OBJECT, FILE);

    Returns Makefile fragment for target 'all' which will run 'pod2text'
    against FILE using the command:

        pod2text FILE > README

    OBJECT is the object provided by ExtUtils::MakeMaker internals.

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

        $ make

    Or,

        $ make all

   release
        my $frag = release(OBJECT, RELEASE_ROOT);

    Returns Makefile fragment for target 'release' 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'.

    RELEASE_ROOT must exist prior to running 'make release'.

    OBJECT is the object provided by ExtUtils::MakeMaker internals.

    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

  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.

