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