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