README
1NAME
2 Module::Compile - Perl Module Compilation
3
4SYNOPSIS
5 package Foo;
6 use Module::Compile -base;
7
8 sub pmc_compile {
9 my ($class, $source) = @_;
10 # Convert $source into (most likely Perl 5) $compiled_output
11 return $compiled_output;
12 }
13
14 In Bar.pm:
15
16 package Bar;
17
18 use Foo;
19 ...
20 no Foo
21
22 or (implied "no Foo;"):
23
24 package Bar;
25
26 {
27 use Foo;
28 ...
29 }
30
31 To compile Bar.pm into Bar.pmc:
32
33 perl -c Bar.pm
34
35DESCRIPTION
36 This module provides a system for writing modules that *compile* other
37 Perl modules.
38
39 Modules that use these compilation modules get compiled into some
40 altered form the first time they are run. The result is cached into
41 ".pmc" files.
42
43 Perl has native support for ".pmc" files. It always checks for them,
44 before loading a ".pm" file.
45
46EXAMPLE
47 You can declare a "v6.pm" compiler with:
48
49 package v6;
50 use Module::Compile -base;
51
52 sub pmc_compile {
53 my ($class, $source) = @_;
54 # ... some way to invoke pugs and give p5 code back ...
55 }
56
57 and use it like:
58
59 # MyModule.pm
60 use v6-pugs;
61 module MyModule;
62 # ...some p6 code here...
63 no v6;
64 # ...back to p5 land...
65
66 On the first time this module is loaded, it will compile Perl 6 blocks
67 into Perl 5 (as soon as the "no v6" line is seen), and merge it with the
68 Perl 5 blocks, saving the result into a MyModule.pmc file.
69
70 The next time around, Perl 5 will automatically load MyModule.pmc when
71 someone says "use MyModule". On the other hand, Perl 6 can run
72 MyModule.pm s a Perl 6 module just fine, as "use v6-pugs" and "no v6"
73 both works in a Perl 6 setting.
74
75 The v6.pm module will also check if MyModule.pmc is up to date. If it
76 is, then it will touch its timestamp so the ".pmc" is loaded on the next
77 time.
78
79BENEFITS
80 Module::Compile compilers gives you the following benefits:
81
82 * Ability to mix many source filterish modules in a much more sane
83 manner. Module::Compile controls the compilation process, calling
84 each compiler at the right time with the right data.
85
86 * Ability to ship precompiled modules without shipping Module::Compile
87 and the compiler modules themselves.
88
89 * Easier debugging of compiled/filtered code. The ".pmc" has the real
90 code you want to see.
91
92 * Zero additional runtime penalty after compilation, because "perl"
93 has already been doing the ".pmc" check on every module load since
94 1999!
95
96PARSING AND DISPATCH
97 NOTE: *** NOT FULLY IMPLEMENTED YET ***
98
99 Module::Compile attempts to make source filtering a sane process, by
100 parsing up your module's source code into various blocks; so that by the
101 time a compiler is called it only gets the source code that it should be
102 looking at.
103
104 This section describes the rather complex algorithm that Module::Compile
105 uses.
106
107 First, the source module is preprocessed to hide heredocs, since the
108 content inside heredocs can possibly confuse further parsing.
109
110 Next, the source module is divided into a shallow tree of blocks:
111
112 PREAMBLE:
113 (SUBROUTINE | BAREBLOCK | POD | PLAIN)S
114 PACKAGES:
115 PREFACE
116 (SUBROUTINE | BAREBLOCK | POD | PLAIN)S
117 DATA
118
119 All of these blocks begin and end on line boundaries. They are described
120 as follows:
121
122 PREAMBLE - Lines before the first C<package> statement.
123 PACKAGES - Lines beginning with a C<package statement and continuing
124 until the next C<package> or C<DATA> section.
125 DATA - The DATA section. Begins with the line C<__DATA__> or
126 C<__END__>.
127 SUBROUTINE - A top level (not nested) subroutine. Ending '}' must be
128 on its own line in the first column.
129 BAREBLOCK - A top level (not nested) code block. Ending '}' must be
130 on its own line in the first column.
131 POD - Pod sections beginning with C<^=\w+> and ending with C<=cut>.
132 PLAIN - Lines not in SUBROUTINE, BAREBLOCK or POD.
133 PREFACE - Lines before the first block in a package.
134
135 Next, all the blocks are scanned for lines like:
136
137 use Foo qw'x y z';
138 no Foo;
139
140 Where Foo is a Module::Compile subclass.
141
142 The lines within a given block between a "use" and "no" statement are
143 marked to be passed to that compiler. The end of an inner block
144 effectively acts as a "no" statement for any compile sections in that
145 block. "use" statements in a PREFACE apply to all the code in a PACKAGE.
146 "use" statements in a PREAMBLE apply to all the code in all PACKAGES.
147
148 After all the code has been parsed into blocks and the blocks have been
149 marked for various compilers, Module::Compile dispatches the code blocks
150 to the compilers. It does so in a most specific to most general order.
151 So inner blocks get compiled first, then outer blocks.
152
153 A compiler may choose to declare that its result not be recompiled by
154 some other containing parser. In this case the result of the compilation
155 is replaced by a single line containing the hexadecimal digest of the
156 result in double quotes followed by a semicolon. Like:
157
158 "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15";
159
160 The rationale of this is that randoms strings are usally left alone by
161 compilers. After all the compilers have finished, the digest lines will
162 be expanded again.
163
164 Every bit of the default process described above is overridable by
165 various methods.
166
167DISTRIBUTION SUPPORT
168 Module::Install makes it terribly easy to prepare a module distribution
169 with compiled .pmc files. Module::Compile installs a
170 Module::Install::PMC plugin. All you need to do is add this line to your
171 Makefile.PL:
172
173 pmc_support;
174
175 Any of your distrbution's modules that use Module::Compile based modules
176 will automatically be compiled into .pmc files and shipped with your
177 distribtution precompiled. This means that people who install your
178 module distribtution do not need to have the compilers installed
179 themselves. So you don't need to make the compiler modules be
180 prerequisites.
181
182SEE ALSO
183 Module::Install
184
185AUTHOR
186 Ingy döt Net <ingy@ingy.net>
187
188COPYRIGHT AND LICENSE
189 Copyright (c) 2006, 2011. Ingy döt Net.
190
191 This program is free software; you can redistribute it and/or modify it
192 under the same terms as Perl itself.
193
194 See http://www.perl.com/perl/misc/Artistic.html
195
196