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