.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Module::Compile 3pm"
.TH Module::Compile 3pm "2022-11-30" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Compile \- Perl Module Compilation
.SH "VERSION"
.IX Header "VERSION"
This document describes Module::Compile version \fB0.38\fR.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package Foo;
\&    use Module::Compile \-base;
\&
\&    sub pmc_compile {
\&        my ($class, $source) = @_;
\&        # Convert $source into (most likely Perl 5) $compiled_output
\&        return $compiled_output;
\&    }
.Ve
.PP
In \f(CW\*(C`Bar.pm\*(C'\fR:
.PP
.Vb 1
\&    package Bar;
\&
\&    use Foo;
\&    ...
\&    no Foo
.Ve
.PP
or (implied \*(L"no Foo;\*(R"):
.PP
.Vb 1
\&    package Bar;
\&
\&    {
\&        use Foo;
\&        ...
\&    }
.Ve
.PP
To compile \f(CW\*(C`Bar.pm\*(C'\fR into \f(CW\*(C`Bar.pmc\*(C'\fR:
.PP
.Vb 1
\&    perl \-c Bar.pm
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a system for writing modules that \fIcompile\fR other
Perl modules.
.PP
Modules that use these compilation modules get compiled into some altered form
the first time they are run. The result is cached into \f(CW\*(C`.pmc\*(C'\fR files.
.PP
Perl has native support for \f(CW\*(C`.pmc\*(C'\fR files. It always checks for them, before
loading a \f(CW\*(C`.pm\*(C'\fR file.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
You can declare a \f(CW\*(C`v6.pm\*(C'\fR compiler with:
.PP
.Vb 2
\&    package v6;
\&    use Module::Compile \-base;
\&
\&    sub pmc_compile {
\&        my ($class, $source) = @_;
\&        # ... some way to invoke pugs and give p5 code back ...
\&    }
.Ve
.PP
and use it like:
.PP
.Vb 6
\&    # MyModule.pm
\&    use v6\-pugs;
\&    module MyModule;
\&    # ...some p6 code here...
\&    no v6;
\&    # ...back to p5 land...
.Ve
.PP
On the first time this module is loaded, it will compile Perl 6 blocks into
Perl 5 (as soon as the \f(CW\*(C`no v6\*(C'\fR line is seen), and merge it with the Perl 5
blocks, saving the result into a \f(CW\*(C`MyModule.pmc\*(C'\fR file.
.PP
The next time around, Perl 5 will automatically load \f(CW\*(C`MyModule.pmc\*(C'\fR when
someone says \f(CW\*(C`use MyModule\*(C'\fR. On the other hand, Perl 6 can run MyModule.pm s
a Perl 6 module just fine, as \f(CW\*(C`use v6\-pugs\*(C'\fR and \f(CW\*(C`no v6\*(C'\fR both works in a Perl
6 setting.
.PP
The \fBv6.pm\fR module will also check if \f(CW\*(C`MyModule.pmc\*(C'\fR is up to date. If
it is, then it will touch its timestamp so the \f(CW\*(C`.pmc\*(C'\fR is loaded on the
next time.
.SH "BENEFITS"
.IX Header "BENEFITS"
Module::Compile compilers gives you the following benefits:
.IP "\(bu" 4
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.
.IP "\(bu" 4
Ability to ship precompiled modules without shipping Module::Compile and the compiler modules themselves.
.IP "\(bu" 4
Easier debugging of compiled/filtered code. The \f(CW\*(C`.pmc\*(C'\fR has the real code you want to see.
.IP "\(bu" 4
Zero additional runtime penalty after compilation, because \f(CW\*(C`perl\*(C'\fR has already been doing the \f(CW\*(C`.pmc\*(C'\fR check on every module load since 1999!
.SH "PARSING AND DISPATCH"
.IX Header "PARSING AND DISPATCH"
\&\s-1NOTE:\s0 *** \s-1NOT FULLY IMPLEMENTED YET\s0 ***
.PP
Module::Compile attempts to make source filtering a sane process, by parsing
up your module's source code into various blocks; so that by the time a
compiler is called it only gets the source code that it should be looking at.
.PP
This section describes the rather complex algorithm that Module::Compile uses.
.PP
First, the source module is preprocessed to hide heredocs, since the content
inside heredocs can possibly confuse further parsing.
.PP
Next, the source module is divided into a shallow tree of blocks:
.PP
.Vb 6
\&    PREAMBLE:
\&      (SUBROUTINE | BAREBLOCK | POD | PLAIN)S
\&    PACKAGES:
\&      PREFACE
\&      (SUBROUTINE | BAREBLOCK | POD | PLAIN)S
\&    DATA
.Ve
.PP
All of these blocks begin and end on line boundaries. They are described
as follows:
.IP "\s-1PREAMBLE\s0" 4
.IX Item "PREAMBLE"
Lines before the first \f(CW\*(C`package\*(C'\fR statement.
.IP "\s-1PACKAGES\s0" 4
.IX Item "PACKAGES"
Lines beginning with a `package statement and continuing
.Sp
.Vb 1
\&    until the next \`package\` or \`DATA\` section.
.Ve
.IP "\s-1DATA\s0" 4
.IX Item "DATA"
The \s-1DATA\s0 section. Begins with the line \f(CW\*(C`_\|_DATA_\|_\*(C'\fR or
.Sp
\&\f(CW\*(C`_\|_END_\|_\*(C'\fR.
.IP "\s-1SUBROUTINE\s0" 4
.IX Item "SUBROUTINE"
A top level (not nested) subroutine. Ending '}' must be
.Sp
on its own line in the first column.
.IP "\s-1BAREBLOCK\s0" 4
.IX Item "BAREBLOCK"
A top level (not nested) code block. Ending '}' must be
.Sp
on its own line in the first column.
.IP "\s-1POD\s0" 4
.IX Item "POD"
Pod sections beginning with \f(CW\*(C`^=\ew+\*(C'\fR and ending with \f(CW\*(C`=cut\*(C'\fR.
.IP "\s-1PLAIN\s0" 4
.IX Item "PLAIN"
Lines not in \s-1SUBROUTINE, BAREBLOCK\s0 or \s-1POD.\s0
.IP "\s-1PREFACE\s0" 4
.IX Item "PREFACE"
Lines before the first block in a package.
.PP
Next, all the blocks are scanned for lines like:
.PP
.Vb 2
\&    use Foo qw\*(Aqx y z\*(Aq;
\&    no Foo;
.Ve
.PP
Where Foo is a Module::Compile subclass.
.PP
The lines within a given block between a \f(CW\*(C`use\*(C'\fR and \f(CW\*(C`no\*(C'\fR statement are marked
to be passed to that compiler. The end of an inner block effectively acts as a
\&\f(CW\*(C`no\*(C'\fR statement for any compile sections in that block. \f(CW\*(C`use\*(C'\fR statements in a
\&\s-1PREFACE\s0 apply to all the code in a \s-1PACKAGE.\s0 \f(CW\*(C`use\*(C'\fR statements in a \s-1PREAMBLE\s0
apply to all the code in all \s-1PACKAGES.\s0
.PP
After all the code has been parsed into blocks and the blocks have been marked
for various compilers, Module::Compile dispatches the code blocks to the
.PP
.Vb 2
\&      compilers. It does so in a most specific to most general order.  So inner
\&      blocks get compiled first, then outer blocks.
.Ve
.PP
A compiler may choose to declare that its result not be recompiled by some
other containing parser. In this case the result of the compilation is
replaced by a single line containing the hexadecimal digest of the result in
double quotes followed by a semicolon. Like:
.PP
.Vb 1
\&    "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15";
.Ve
.PP
The rationale of this is that random strings are usually left alone by
compilers. After all the compilers have finished, the digest lines will be
expanded again.
.PP
Every bit of the default process described above is overridable by
various methods.
.SH "DISTRIBUTION SUPPORT"
.IX Header "DISTRIBUTION SUPPORT"
Module::Install makes it terribly easy to prepare a module distribution with
compiled .pmc files. See Module::Install::PMC. All you need to do is add this
line to your Makefile.PL:
.PP
.Vb 1
\&    pmc_support;
.Ve
.PP
Any of your distrbution's modules that use Module::Compile based modules will
automatically be compiled into .pmc files and shipped with your distribtution
precompiled. This means that people who install your module distribtution do
not need to have the compilers installed themselves. So you don't need to make
the compiler modules be prerequisites.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
Module::Install
.IP "\(bu" 4
Module::Install::PMC
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Ingy döt Net <ingy@cpan.org>
.IP "\(bu" 4
Audrey Tang <audreyt@audreyt.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2006\-2019. Ingy döt Net.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.PP
See <http://www.perl.com/perl/misc/Artistic.html>