1 Perl Compiler Kit, Version alpha3
3 Copyright (c) 1996, Malcolm Beattie
5 This program is free software; you can redistribute it and/or modify
6 it under the terms of either:
8 a) the GNU General Public License as published by the Free
9 Software Foundation; either version 1, or (at your option) any
12 b) the "Artistic License" which comes with this kit.
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
17 the GNU General Public License or the Artistic License for more details.
19 You should have received a copy of the Artistic License with this kit,
20 in the file named "Artistic". If not, you can get one from the Perl
21 distribution. You should also have received a copy of the GNU General
22 Public License, in the file named "Copying". If not, you can get one
23 from the Perl distribution or else write to the Free Software
24 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
29 CC backend now supports ".." and s//e.
30 Xref backend generates cross-reference reports
31 Cleanups to fix benign but irritating "-w" warnings
35 Shared globs and pre-initialised hash support
41 (1) You need perl5.002 or perl5.003.
43 (2) If you want to compile and run programs with the C or CC backends
44 which undefine (or redefine) subroutines, then you need to apply a
45 one-line patch to perl itself. One or two of the programs in perl's
46 own test suite do this. The patch is in file op.patch. It prevents
47 perl from calling free() on OPs with the magic sequence number (U16)-1.
48 The compiler declares all OPs as static structures and uses that magic
53 to write a personalised Makefile for your system. If you want the
54 bytecode modules to support reading bytecode from strings (instead of
55 just from files) then add the option
56 -DINDIRECT_BGET_MACROS
57 into the middle of the definition of the CCCMD macro in the Makefile.
58 Your C compiler may need to be able to cope with Standard C for this.
59 I haven't tested this option yet with an old pre-Standard compiler.
61 (4) If your platform supports dynamic loading then just type
64 perl -Iblib/arch -MO=foo bar baz
65 to use the compiler modules (see later for details).
66 If you need/want instead to make a statically linked perl which
67 contains the appropriate modules, then type
71 ./bperl -MO=foo bar baz
72 to use the compiler modules.
73 In both cases, the byteperl executable is required for running standalone
74 bytecode programs. It is *not* a standard perl+XSUB perl executable.
78 As of the alpha3 release, the Bytecode, C and CC backends are now all
79 functional enough to compile almost the whole of the main perl test
80 suite. In the case of the CC backend, any failures are all due to
81 differences and/or known bugs documented below. See the file TESTS.
82 In the following examples, you'll need to replace "perl" by
84 if you have built the extensions for a dynamic loading platform but
85 haven't installed the extensions completely. You'll need to replace
88 if you have built the extensions into a statically linked perl binary.
90 (1) To compile perl program foo.pl with the C backend, do
91 perl -MO=C,-ofoo.c foo.pl
92 Then use the cc_harness perl program to compile the resulting C source:
93 perl cc_harness -O2 -o foo foo.c
95 If you are using a non-ANSI pre-Standard C compiler that can't handle
96 pre-declaring static arrays, then add -DBROKEN_STATIC_REDECL to the
98 perl cc_harness -O2 -o foo -DBROKEN_STATIC_REDECL foo.c
99 If you are using a non-ANSI pre-Standard C compiler that can't handle
100 static initialisation of structures with union members then add
101 -DBROKEN_UNION_INIT to the options you use. If you want command line
102 arguments passed to your executable to be interpreted by perl (e.g. -Dx)
103 then compile foo.c with -DALLOW_PERL_OPTIONS. Otherwise, all command line
104 arguments passed to foo will appear directly in @ARGV. The resulting
105 executable foo is the compiled version of foo.pl. See the file NOTES for
106 extra options you can pass to -MO=C.
108 There are some constraints on the contents on foo.pl if you want to be
109 able to compile it successfully. Some problems can be fixed fairly easily
110 by altering foo.pl; some problems with the compiler are known to be
111 straightforward to solve and I'll do so soon. The file Todo lists a
112 number of known problems. See the XSUB section lower down for information
113 about compiling programs which use XSUBs.
115 (2) To compile foo.pl with the CC backend (which generates actual
116 optimised C code for the execution path of your perl program), use
117 perl -MO=CC,-ofoo.c foo.pl
119 and proceed just as with the C backend. You should almost certainly
120 use an option such as -O2 with the subsequent cc_harness invocation
121 so that your C compiler uses optimisation. The C code generated by
122 the Perl compiler's CC backend looks ugly to humans but is easily
123 optimised by C compilers.
125 To make the most of this compiler backend, you need to tell the
126 compiler when you're using int or double variables so that it can
127 optimise appropriately (although this part of the compiler is the most
128 buggy). You currently do that by naming lexical variables ending in
129 "_i" for ints, "_d" for doubles, "_ir" for int "register" variables or
130 "_dr" for double "register" variables. Here "register" is a promise
131 that you won't pass a reference to the variable into a sub which then
132 modifies the variable. The compiler ought to catch attempts to use
133 "\$i" just as C compilers catch attempts to do "&i" for a register int
134 i but it doesn't at the moment. Bugs in the CC backend may make your
135 program fail in mysterious ways and give wrong answers rather than just
136 crash in boring ways. But, hey, this is an alpha release so you knew
137 that anyway. See the XSUB section lower down for information about
138 compiling programs which use XSUBs.
140 If your program uses classes which define methods (or other subs which
141 are not exported and not apparently used until runtime) then you'll
142 need to use -u compile-time options (see the NOTES file) to force the
143 subs to be compiled. Future releases will probably default the other
144 way, do more auto-detection and provide more fine-grained control.
146 Since compiled executables need linking with libperl, you may want
147 to turn libperl.a into a shared library if your platform supports
148 it. For example, with Digital UNIX, do something like
149 ld -shared -o libperl.so -all libperl.a -none -lc
150 and with Linux/ELF, rebuild the perl .c files with -fPIC (and I
151 also suggest -fomit-frame-pointer for Linux on Intel architetcures),
152 do "Make libperl.a" and then do
153 gcc -shared -Wl,-soname,libperl.so.5 -o libperl.so.5.3 `ar t libperl.a`
155 # cp libperl.so.5.3 /usr/lib
157 # ln -s libperl.so.5.3 libperl.so.5
158 # ln -s libperl.so.5 libperl.so
160 When you compile perl executables with cc_harness, append -L/usr/lib
161 otherwise the -L for the perl source directory will override it. For
163 perl -Iblib/arch -MO=CC,-O2,-ofoo3.c foo3.bench
164 perl cc_harness -o foo3 -O2 foo3.c -L/usr/lib
166 -rwxr-xr-x 1 mbeattie xzdg 11218 Jul 1 15:28 foo3
167 You'll probably also want to link your main perl executable against
168 libperl.so; it's nice having an 11K perl executable.
170 (3) To compile foo.pl into bytecode do
171 perl -MO=Bytecode,-ofoo foo.pl
172 To run the resulting bytecode file foo as a standalone program, you
173 use the program byteperl which should have been built along with the
176 Any extra arguments are passed in as @ARGV; they are not interpreted
177 as perl options. If you want to load chunks of bytecode into an already
178 running perl program then use the -m option and investigate the
179 byteload_fh and byteload_string functions exported by the B module.
180 See the NOTES file for details of these and other options (including
181 optimisation options and ways of getting at the intermediate "assembler"
182 code that the Bytecode backend uses).
184 (3) There are little Bourne shell scripts and perl programs to aid with
185 some common operations: assemble, disassemble, run_bytecode_test,
186 run_test, cc_harness, test_harness, test_harness_bytecode.
188 (4) Walk the op tree in execution order printing terse info about each op
189 perl -MO=Terse,exec foo.pl
191 (5) Walk the op tree in syntax order printing lengthier debug info about
192 each op. You can also append ",exec" to walk in execution order, but the
193 formatting is designed to look nice with Terse rather than Debug.
194 perl -MO=Debug foo.pl
196 (6) Produce a cross-reference report of the line numbers at which all
197 variables, subs and formats are defined and used.
202 The C and CC backends can successfully compile some perl programs which
203 make use of XSUB extensions. [I'll add more detail to this section in a
204 later release.] As a prerequisite, such extensions must not need to do
205 anything in their BOOT: section which needs to be done at runtime rather
206 than compile time. Normally, the only code in the boot_Foo() function is
207 a list of newXS() calls which xsubpp puts there and the compiler handles
208 saving those XS subs itself. For each XSUB used, the C and CC compiler
209 will generate an initialiser in their C output which refers to the name
210 of the relevant C function (XS_Foo_somesub). What is not yet automated
211 is the necessary commands and cc command-line options (e.g. via
212 "perl cc_harness") which link against the extension libraries. For now,
213 you need the XSUB extension to have installed files in the right format
214 for using as C libraries (e.g. Foo.a or Foo.so). As the Foo.so files (or
215 your platform's version) aren't suitable for linking against, you will
216 have to reget the extension source and rebuild it as a static extension
217 to force the generation of a suitable Foo.a file. Then you need to make
218 a symlink (or copy or rename) of that file into a libFoo.a suitable for
219 cc linking. Then add the appropriate -L and -l options to your
220 "perl cc_harness" command line to find and link against those libraries.
221 You may also need to fix up some platform-dependent environment variable
222 to ensure that linked-against .so files are found at runtime too.
226 The result of running a compiled Perl program can sometimes be different
227 from running the same program with standard perl. Think of the compiler
228 as having a slightly different implementation of the language Perl.
229 Unfortunately, since Perl has had a single implementation until now,
230 there are no formal standards or documents defining what behaviour is
231 guaranteed of Perl the language and what just "happens to work".
232 Some of the differences below are almost impossible to change because of
233 the way the compiler works. Others can be changed to produce "standard"
234 perl behaviour if it's deemed proper and the resulting performance hit
235 is accepted. I'll use "standard perl" to mean the result of running a
236 Perl program using the perl executable from the perl distribution.
237 I'll use "compiled Perl program" to mean running an executable produced
238 by this compiler kit ("the compiler") with the CC backend.
241 Standard perl calculates the target of "next", "last", and "redo"
242 at run-time. The compiler calculates the targets at compile-time.
243 For example, the program
245 sub skip_on_odd { next NUMBER if $_[0] % 2 }
246 NUMBER: for ($i = 0; $i < 5; $i++) {
253 with standard perl but gives a compile-time error with the compiler.
256 The context (scalar or array) of the ".." operator determines whether
257 it behaves as a range or a flip/flop. Standard perl delays until
258 runtime the decision of which context it is in but the compiler needs
259 to know the context at compile-time. For example,
261 sub range { (shift @a)..(shift @a) }
263 while (@a) { print scalar(range()) }
266 with standard Perl but gives a compile-time error with compiled Perl.
269 Compiled Perl programs use native C arithemtic much more frequently
270 than standard perl. Operations on large numbers or on boundary
271 cases may produce different behaviour.
274 Features of standard perl such as $[ which have been deprecated
275 in standard perl since version 5 was released have not been
276 implemented in the compiler.
279 I'll add to this list as I remember what they are.
283 Here are some things which may cause the compiler problems.
285 The following render the compiler useless (without serious hacking):
286 * Use of the DATA filehandle (via __END__ or __DATA__ tokens)
287 * Operator overloading with %OVERLOAD
288 * The (deprecated) magic array-offset variable $[ does not work
289 * The following operators are not yet implemented for CC
291 sort with a non-default comparison (i.e. a named sub or inline block)
292 * You can't use "last" to exit from a non-loop block.
294 The following may give significant problems:
295 * BEGIN blocks containing complex initialisation code
296 * Code which is only ever referred to at runtime (e.g. via eval "..." or
297 via method calls): see the -u option for the C and CC backends.
298 * Run-time lookups of lexical variables in "outside" closures
300 The following may cause problems (not thoroughly tested):
301 * Dependencies on whether values of some "magic" Perl variables are
302 determined at compile-time or runtime.
303 * For the C and CC backends: compile-time strings which are longer than
304 your C compiler can cope with in a single line or definition.
305 * Reliance on intimate details of global destruction
306 * For the Bytecode backend: high -On optimisation numbers with code
307 that has complex flow of control.
308 * Any "-w" option in the first line of your perl program is seen and
309 acted on by perl itself before the compiler starts. The compiler
310 itself then runs with warnings turned on. This may cause perl to
311 print out warnings about the compiler itself since I haven't tested
312 it thoroughly with warnings turned on.
314 There is a terser but more complete list in the Todo file.