Commit | Line | Data |
a798dbf2 |
1 | package O; |
059a8bb7 |
2 | use B qw(minus_c save_BEGINs); |
a798dbf2 |
3 | use Carp; |
4 | |
5 | sub import { |
6 | my ($class, $backend, @options) = @_; |
7 | eval "use B::$backend ()"; |
8 | if ($@) { |
9 | croak "use of backend $backend failed: $@"; |
10 | } |
11 | my $compilesub = &{"B::${backend}::compile"}(@options); |
12 | if (ref($compilesub) eq "CODE") { |
13 | minus_c; |
059a8bb7 |
14 | save_BEGINs; |
7d30b5c4 |
15 | eval 'CHECK { &$compilesub() }'; |
a798dbf2 |
16 | } else { |
17 | die $compilesub; |
18 | } |
19 | } |
20 | |
21 | 1; |
22 | |
7f20e9dd |
23 | __END__ |
24 | |
25 | =head1 NAME |
26 | |
27 | O - Generic interface to Perl Compiler backends |
28 | |
29 | =head1 SYNOPSIS |
30 | |
31 | perl -MO=Backend[,OPTIONS] foo.pl |
32 | |
33 | =head1 DESCRIPTION |
34 | |
1a52ab62 |
35 | This is the module that is used as a frontend to the Perl Compiler. |
36 | |
37 | =head1 CONVENTIONS |
38 | |
39 | Most compiler backends use the following conventions: OPTIONS |
40 | consists of a comma-separated list of words (no white-space). |
41 | The C<-v> option usually puts the backend into verbose mode. |
42 | The C<-ofile> option generates output to B<file> instead of |
43 | stdout. The C<-D> option followed by various letters turns on |
44 | various internal debugging flags. See the documentation for the |
45 | desired backend (named C<B::Backend> for the example above) to |
46 | find out about that backend. |
47 | |
48 | =head1 IMPLEMENTATION |
49 | |
50 | This section is only necessary for those who want to write a |
51 | compiler backend module that can be used via this module. |
52 | |
53 | The command-line mentioned in the SYNOPSIS section corresponds to |
54 | the Perl code |
55 | |
56 | use O ("Backend", OPTIONS); |
57 | |
58 | The C<import> function which that calls loads in the appropriate |
59 | C<B::Backend> module and calls the C<compile> function in that |
60 | package, passing it OPTIONS. That function is expected to return |
61 | a sub reference which we'll call CALLBACK. Next, the "compile-only" |
62 | flag is switched on (equivalent to the command-line option C<-c>) |
7d30b5c4 |
63 | and a CHECK block is registered which calls CALLBACK. Thus the main |
1a52ab62 |
64 | Perl program mentioned on the command-line is read in, parsed and |
65 | compiled into internal syntax tree form. Since the C<-c> flag is |
66 | set, the program does not start running (excepting BEGIN blocks of |
67 | course) but the CALLBACK function registered by the compiler |
68 | backend is called. |
69 | |
70 | In summary, a compiler backend module should be called "B::Foo" |
71 | for some foo and live in the appropriate directory for that name. |
72 | It should define a function called C<compile>. When the user types |
73 | |
74 | perl -MO=Foo,OPTIONS foo.pl |
75 | |
76 | that function is called and is passed those OPTIONS (split on |
77 | commas). It should return a sub ref to the main compilation function. |
78 | After the user's program is loaded and parsed, that returned sub ref |
79 | is invoked which can then go ahead and do the compilation, usually by |
80 | making use of the C<B> module's functionality. |
7f20e9dd |
81 | |
82 | =head1 AUTHOR |
83 | |
84 | Malcolm Beattie, C<mbeattie@sable.ox.ac.uk> |
85 | |
86 | =cut |