contrib/perl5/ext/B/README

   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
  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.
  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