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

NAME

6       Module::Compile - Perl Module Compilation
7

VERSION

9       This document describes Module::Compile version 0.38.
10

SYNOPSIS

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

DESCRIPTION

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

EXAMPLE

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

BENEFITS

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

PARSING AND DISPATCH

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

DISTRIBUTION SUPPORT

196       Module::Install makes it terribly easy to prepare a module distribution
197       with compiled .pmc files. See Module::Install::PMC. All you need to do
198       is add this line to your Makefile.PL:
199
200           pmc_support;
201
202       Any of your distrbution's modules that use Module::Compile based
203       modules will automatically be compiled into .pmc files and shipped with
204       your distribtution precompiled. This means that people who install your
205       module distribtution do not need to have the compilers installed
206       themselves. So you don't need to make the compiler modules be
207       prerequisites.
208

SEE ALSO

210       •   Module::Install
211
212       •   Module::Install::PMC
213

AUTHORS

215       •   Ingy döt Net <ingy@cpan.org>
216
217       •   Audrey Tang <audreyt@audreyt.org>
218

COPYRIGHT AND LICENSE

220       Copyright 2006-2019. Ingy döt Net.
221
222       This program is free software; you can redistribute it and/or modify it
223       under the same terms as Perl itself.
224
225       See <http://www.perl.com/perl/misc/Artistic.html>
226
227
228
229perl v5.36.0                      2022-07-22                Module::Compile(3)