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