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