1Module::Compile(3)    User Contributed Perl Documentation   Module::Compile(3)
2
3
4

NAME

6       Module::Compile - Perl Module Compilation
7

SYNOPSIS

9           package Foo;
10           use Module::Compile -base;
11
12           sub pmc_compile {
13               my ($class, $source) = @_;
14               # Convert $source into (most likely Perl 5) $compiled_output
15               return $compiled_output;
16           }
17
18       In Bar.pm:
19
20           package Bar;
21
22           use Foo;
23           ...
24           no Foo
25
26       or (implied "no Foo;"):
27
28           package Bar;
29
30           {
31               use Foo;
32               ...
33           }
34
35       To compile Bar.pm into Bar.pmc:
36
37           perl -c Bar.pm
38

DESCRIPTION

40       This module provides a system for writing modules that compile other
41       Perl modules.
42
43       Modules that use these compilation modules get compiled into some
44       altered form the first time they are run. The result is cached into
45       ".pmc" files.
46
47       Perl has native support for ".pmc" files. It always checks for them,
48       before loading a ".pm" file.
49

EXAMPLE

51       You can declare a "v6.pm" compiler with:
52
53           package v6;
54           use Module::Compile -base;
55
56           sub pmc_compile {
57               my ($class, $source) = @_;
58               # ... some way to invoke pugs and give p5 code back ...
59           }
60
61       and use it like:
62
63           # MyModule.pm
64           use v6-pugs;
65           module MyModule;
66           # ...some p6 code here...
67           no v6;
68           # ...back to p5 land...
69
70       On the first time this module is loaded, it will compile Perl 6 blocks
71       into Perl 5 (as soon as the "no v6" line is seen), and merge it with
72       the Perl 5 blocks, saving the result into a MyModule.pmc file.
73
74       The next time around, Perl 5 will automatically load MyModule.pmc when
75       someone says "use MyModule". On the other hand, Perl 6 can run MyMod‐
76       ule.pm s a Perl 6 module just fine, as "use v6-pugs" and "no v6" both
77       works in a Perl 6 setting.
78
79       The v6.pm module will also check if MyModule.pmc is up to date. If it
80       is, then it will touch its timestamp so the ".pmc" is loaded on the
81       next time.
82

BENEFITS

84       Module::Compile compilers gives you the following benefits:
85
86       ·   Ability to mix many source filterish modules in a much more sane
87           manner.  Module::Compile controls the compilation process, calling
88           each compiler at the right time with the right data.
89
90       ·   Ability to ship precompiled modules without shipping Module::Com‐
91           pile and the compiler modules themselves.
92
93       ·   Easier debugging of compiled/filtered code. The ".pmc" has the real
94           code you want to see.
95
96       ·   Zero additional runtime penalty after compilation, because "perl"
97           has already been doing the ".pmc" check on every module load since
98           1999!
99

PARSING AND DISPATCH

101       NOTE: *** NOT FULLY IMPLEMENTED YET ***
102
103       Module::Compile attempts to make source filtering a sane process, by
104       parsing up your module's source code into various blocks; so that by
105       the time a compiler is called it only gets the source code that it
106       should be looking at.
107
108       This section describes the rather complex algorithm that Module::Com‐
109       pile uses.
110
111       First, the source module is preprocessed to hide heredocs, since the
112       content inside heredocs can possibly confuse further parsing.
113
114       Next, the source module is divided into a shallow tree of blocks:
115
116           PREAMBLE:
117               (SUBROUTINE ⎪ BAREBLOCK ⎪ POD ⎪ PLAIN)S
118           PACKAGES:
119               PREFACE
120               (SUBROUTINE ⎪ BAREBLOCK ⎪ POD ⎪ PLAIN)S
121           DATA
122
123       All of these blocks begin and end on line boundaries. They are
124       described as follows:
125
126           PREAMBLE - Lines before the first C<package> statement.
127           PACKAGES - Lines beginning with a C<package statement and continuing
128               until the next C<package> or C<DATA> section.
129           DATA - The DATA section. Begins with the line C<__DATA__> or
130               C<__END__>.
131           SUBROUTINE - A top level (not nested) subroutine. Ending '}' must be
132               on its own line in the first column.
133           BAREBLOCK - A top level (not nested) code block. Ending '}' must be
134               on its own line in the first column.
135           POD - Pod sections beginning with C<^=\w+> and ending with C<=cut>.
136           PLAIN - Lines not in SUBROUTINE, BAREBLOCK or POD.
137           PREFACE - Lines before the first block in a package.
138
139       Next, all the blocks are scanned for lines like:
140
141           use Foo qw'x y z';
142           no Foo;
143
144       Where Foo is a Module::Compile subclass.
145
146       The lines within a given block between a "use" and "no" statement are
147       marked to be passed to that compiler. The end of an inner block effec‐
148       tively acts as a "no" statement for any compile sections in that block.
149       "use" statements in a PREFACE apply to all the code in a PACKAGE. "use"
150       statements in a PREAMBLE apply to all the code in all PACKAGES.
151
152       After all the code has been parsed into blocks and the blocks have been
153       marked for various compilers, Module::Compile dispatches the code
154       blocks to the compilers. It does so in a most specific to most general
155       order.  So inner blocks get compiled first, then outer blocks.
156
157       A compiler may choose to declare that its result not be recompiled by
158       some other containing parser. In this case the result of the compila‐
159       tion is replaced by a single line containing the hexadecimal digest of
160       the result in double quotes followed by a semicolon. Like:
161
162           "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15";
163
164       The rationale of this is that randoms strings are usally left alone by
165       compilers. After all the compilers have finished, the digest lines will
166       be expanded again.
167
168       Every bit of the default process described above is overridable by var‐
169       ious methods.
170

DISTRIBUTION SUPPORT

172       Module::Install makes it terribly easy to prepare a module distribution
173       with compiled .pmc files. Module::Compile installs a Mod‐
174       ule::Install::PMC plugin. All you need to do is add this line to your
175       Makefile.PL:
176
177           pmc_support;
178
179       Any of your distrbution's modules that use Module::Compile based mod‐
180       ules will automatically be compiled into .pmc files and shipped with
181       your distribtution precompiled. This means that people who install your
182       module distribtution do not need to have the compilers installed them‐
183       selves. So you don't need to make the compiler modules be prerequi‐
184       sites.
185

SEE ALSO

187       Module::Install
188

AUTHORS

190       Ingy döt Net <ingy@cpan.org>
191
192       Audrey Tang <autrijus@autrijus.org>
193

COPYRIGHT

195       Copyright (c) 2006. Ingy döt Net. All rights reserved.
196
197       This program is free software; you can redistribute it and/or modify it
198       under the same terms as Perl itself.
199
200       See <http://www.perl.com/perl/misc/Artistic.html>
201
202
203
204perl v5.8.8                       2006-10-17                Module::Compile(3)