Commit | Line | Data |
a798dbf2 |
1 | package O; |
28b605d8 |
2 | |
3 | our $VERSION = '1.00'; |
4 | |
059a8bb7 |
5 | use B qw(minus_c save_BEGINs); |
a798dbf2 |
6 | use Carp; |
7 | |
8 | sub import { |
34a48b4b |
9 | my ($class, @options) = @_; |
485988ae |
10 | my ($quiet, $veryquiet) = (0, 0); |
11 | if ($options[0] eq '-q' || $options[0] eq '-qq') { |
34a48b4b |
12 | $quiet = 1; |
34a48b4b |
13 | open (SAVEOUT, ">&STDOUT"); |
14 | close STDOUT; |
15 | open (STDOUT, ">", \$O::BEGIN_output); |
485988ae |
16 | if ($options[0] eq '-qq') { |
17 | $veryquiet = 1; |
18 | } |
19 | shift @options; |
34a48b4b |
20 | } |
21 | my $backend = shift (@options); |
7a9b44b9 |
22 | eval q[ |
23 | BEGIN { |
24 | minus_c; |
25 | save_BEGINs; |
26 | } |
27 | |
28 | CHECK { |
34a48b4b |
29 | if ($quiet) { |
30 | close STDOUT; |
31 | open (STDOUT, ">&SAVEOUT"); |
32 | close SAVEOUT; |
33 | } |
7a9b44b9 |
34 | use B::].$backend.q[ (); |
35 | if ($@) { |
36 | croak "use of backend $backend failed: $@"; |
37 | } |
38 | |
39 | |
40 | my $compilesub = &{"B::${backend}::compile"}(@options); |
41 | if (ref($compilesub) ne "CODE") { |
42 | die $compilesub; |
43 | } |
44 | |
d2bc402e |
45 | local $savebackslash = $\; |
46 | local ($\,$",$,) = (undef,' ',''); |
7a9b44b9 |
47 | &$compilesub(); |
485988ae |
48 | |
49 | close STDERR if $veryquiet; |
7a9b44b9 |
50 | } |
51 | ]; |
52 | die $@ if $@; |
a798dbf2 |
53 | } |
54 | |
55 | 1; |
56 | |
7f20e9dd |
57 | __END__ |
58 | |
59 | =head1 NAME |
60 | |
61 | O - Generic interface to Perl Compiler backends |
62 | |
63 | =head1 SYNOPSIS |
64 | |
34a48b4b |
65 | perl -MO=[-q,]Backend[,OPTIONS] foo.pl |
7f20e9dd |
66 | |
67 | =head1 DESCRIPTION |
68 | |
1a52ab62 |
69 | This is the module that is used as a frontend to the Perl Compiler. |
70 | |
34a48b4b |
71 | If you pass the C<-q> option to the module, then the STDOUT |
72 | filehandle will be redirected into the variable C<$O::BEGIN_output> |
73 | during compilation. This has the effect that any output printed |
74 | to STDOUT by BEGIN blocks or use'd modules will be stored in this |
75 | variable rather than printed. It's useful with those backends which |
76 | produce output themselves (C<Deparse>, C<Concise> etc), so that |
77 | their output is not confused with that generated by the code |
78 | being compiled. |
79 | |
485988ae |
80 | The C<-qq> option behaves like C<-q>, except that it also closes |
81 | STDERR after deparsing has finished. This suppresses the "Syntax OK" |
82 | message normally produced by perl. |
83 | |
1a52ab62 |
84 | =head1 CONVENTIONS |
85 | |
86 | Most compiler backends use the following conventions: OPTIONS |
87 | consists of a comma-separated list of words (no white-space). |
88 | The C<-v> option usually puts the backend into verbose mode. |
89 | The C<-ofile> option generates output to B<file> instead of |
90 | stdout. The C<-D> option followed by various letters turns on |
91 | various internal debugging flags. See the documentation for the |
92 | desired backend (named C<B::Backend> for the example above) to |
93 | find out about that backend. |
94 | |
95 | =head1 IMPLEMENTATION |
96 | |
97 | This section is only necessary for those who want to write a |
98 | compiler backend module that can be used via this module. |
99 | |
100 | The command-line mentioned in the SYNOPSIS section corresponds to |
101 | the Perl code |
102 | |
103 | use O ("Backend", OPTIONS); |
104 | |
105 | The C<import> function which that calls loads in the appropriate |
106 | C<B::Backend> module and calls the C<compile> function in that |
107 | package, passing it OPTIONS. That function is expected to return |
108 | a sub reference which we'll call CALLBACK. Next, the "compile-only" |
109 | flag is switched on (equivalent to the command-line option C<-c>) |
7d30b5c4 |
110 | and a CHECK block is registered which calls CALLBACK. Thus the main |
1a52ab62 |
111 | Perl program mentioned on the command-line is read in, parsed and |
112 | compiled into internal syntax tree form. Since the C<-c> flag is |
113 | set, the program does not start running (excepting BEGIN blocks of |
114 | course) but the CALLBACK function registered by the compiler |
115 | backend is called. |
116 | |
117 | In summary, a compiler backend module should be called "B::Foo" |
118 | for some foo and live in the appropriate directory for that name. |
119 | It should define a function called C<compile>. When the user types |
120 | |
121 | perl -MO=Foo,OPTIONS foo.pl |
122 | |
123 | that function is called and is passed those OPTIONS (split on |
124 | commas). It should return a sub ref to the main compilation function. |
125 | After the user's program is loaded and parsed, that returned sub ref |
126 | is invoked which can then go ahead and do the compilation, usually by |
127 | making use of the C<B> module's functionality. |
7f20e9dd |
128 | |
129 | =head1 AUTHOR |
130 | |
131 | Malcolm Beattie, C<mbeattie@sable.ox.ac.uk> |
132 | |
133 | =cut |