NAME
    Module::Compile - Perl Module Compilation

SYNOPSIS
        package Foo;
        use Module::Compile -base;

        sub pmc_compile {
            my ($class, $source) = @_;
            # Convert $source into (most like Perl 5) $compiled_output
            return $compiled_output;
        }

    In Bar.pm:

        package Bar;
    
        use Foo;
        ...
        no Foo

    To compile Bar.pm into Bar.pmc:

        perl -c Bar.pm

DESCRIPTION
    This module provides a system for writing Perl module compilation
    modules.

    Modules that use these compilation modules get compiled into some
    altered form the first time they are run. The result is cached into
    ".pmc" files.

    Perl has native support for ".pmc" files. It always checks for them,
    before loading a ".pm" file.

    You get the following benefits:

A PERL 6 EXAMPLE
    You can declare a preprocessor with:

        package v6;
        use Module::Compile -base;
    
        sub pmc_compile {
            my ($class, $source) = @_;
            ... some way to invoke pugs and give p5 code back ...
        }

    and use it like:

        # User.pm
        use v6-pugs;
        module User;
        ...some p6 code here...
        no v6;
        ...back to p5 land...

    On the first time this module is loaded, it will compile Perl 6 chunks
    into Perl 5 (as soon as the "no v6" line is seen), and merge it with the
    Perl 5 chunks, saving the result into a User.pmc file.

    The next time around, Perl 5 will automatically load User.pmc when
    someone says "use Foo". On the other hand, Perl 6 can run User.pm as a
    Perl 6 module just fine, as "use v6-pugs" and "no v6" both works in a
    perl 6 setting also.

    The pmc module will imbue v6.pm with the ability to check for Foo.pmc's
    updatedness also, and if it's up to date, then it'd touch its timestamp
    so the .pmc is loaded on the next time.

BENEFITS
    Using Module::Compile compilers gives you the following benefits:

    *   Ability to mix many source filterish modules in a much more sane
        manner. Module::Compile controls the compilation process, calling
        each compiler at the right time with the right data.

    *   Ability to ship precompiled modules without shipping Module::Compile
        and the compiler modules themselves.

    *   Easier debugging of compiled/filtered code. The ".pmc" has the real
        code you want to see.

    *   Zero runtime penalty after compilation. "perl" has already been
        doing the ".pmc" check on every module load since 1999!

AUTHORS
    Audrey Tang <autrijus@autrijus.org>

    Ingy döt Net <ingy@cpan.org>

COPYRIGHT
    Copyright (c) 2006. Ingy döt Net. All rights reserved.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See <http://www.perl.com/perl/misc/Artistic.html>

