Debian Codegraph @

README

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