| 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 |
|