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