view release on metacpan or  search on metacpan

README  view on Meta::CPAN

USAGE

The Bytecode, C and CC backends are now all functional
enough to compile almost the whole of the main perl test
suite and 99-100% of the top100 modules.

Bytecode was broken upstream with 5.22
CC added a lot of new failures with 5.24
cperl is far superior over perl5, esp. with its advanced compiler
support and less breakage.

In the case of the CC backend, any failures are all
due to differences and/or known bugs documented below.
See the file TESTS.

(1) To compile perl program foo.pl with the C backend, do

    perl -MO=C,-ofoo.c foo.pl

Then use the cc_harness perl program to compile the
resulting C source:

    perl cc_harness -O2 -o foo foo.c

If you are using a non-ANSI pre-Standard C compiler that
can't handle pre-declaring static arrays, then add
-DBROKEN_STATIC_REDECL to the options you use:

    perl cc_harness -O2 -o foo -DBROKEN_STATIC_REDECL foo.c

If you are using a non-ANSI pre-Standard C compiler that
can't handle static initialisation of structures with union
members then add -DBROKEN_UNION_INIT to the options you
use. If you want command line arguments passed to your
executable to be interpreted by perl (e.g. -Dx) then compile
foo.c with -DALLOW_PERL_OPTIONS. Otherwise, all command line
arguments passed to foo will appear directly in @ARGV.  The
resulting executable foo is the compiled version of
foo.pl. See the file NOTES for extra options you can pass to
-MO=C.

There are some constraints on the contents on foo.pl if you
want to be able to compile it successfully. Some problems
can be fixed fairly easily by altering foo.pl; some problems
with the compiler are known to be straightforward to solve
and I'll do so soon. The file Todo lists a number of known
problems. See the XSUB section lower down for information
about compiling programs which use XSUBs.

(2) To compile foo.pl with the CC backend (which generates
actual optimised C code for the execution path of your perl
program), use

    perl -MO=CC,-ofoo.c foo.pl

and proceed just as with the C backend. You should almost
certainly use an option such as -O2 with the subsequent
cc_harness invocation so that your C compiler uses
optimisation. The C code generated by the Perl compiler's CC
backend looks ugly to humans but is easily optimised by C
compilers.

To make the most of this optimizing compiler backend, you need to tell
the compiler when you're using int or double variables so that it can
optimise appropriately. The old deprecated way do that was by naming
lexical variables ending in "_i" for ints, "_d" for doubles, "_ir" for
int "register" variables or "_dr" for double "register"
variables. Here "register" is a promise that you won't pass a
reference to the variable into a sub which then modifies the variable.
The new way is to declare those lexicals with "my int" and "my
double". The compiler ought to catch attempts to use "\$i" just as C
compilers catch attempts to do "&i" for a register int i, but it
doesn't at the moment. Bugs in the CC backend may make your program
fail in mysterious ways and give wrong answers rather than just crash
in boring ways. CC is still on the experimental level. Please use your 
test suite.

If your program uses classes which define methods (or other subs which
are not exported and not apparently used until runtime) then you'll
need to use -u compile-time options (see the NOTES file) to force the
subs to be compiled. Future releases will probably default the other
way, do more auto-detection and provide more fine-grained control.

Since compiled executables need linking with libperl, you
may want to turn libperl.a into a shared library if your
platform supports it, -Duseshrplib.
You'll probably also want to link your main perl executable
against libperl.so; it's nice having an 11K perl executable.

(3) To compile foo.pl into bytecode do

    perl -MO=Bytecode,-ofoo.plc foo.pl

To run the resulting bytecode file foo.plc, you use the
ByteLoader module which should have been built along with
the extensions.

    perl -MByteLoader foo.plc

Previous Perl releases had ByteLoader in CORE, so you can omit 
-MByteLoader there.
You can also do -H to automatically use ByteLoader

    perl -MO=Bytecode,-H,-ofoo.plc foo.pl
    perl foo.plc

Any extra arguments are passed in as @ARGV; they are not interpreted
as perl options.
See the NOTES file for details of these and other options (including
optimisation options and ways of getting at the intermediate "assembler"
code that the Bytecode backend uses).

(3) There are little Bourne shell scripts and perl programs to aid with
some common operations:

  perlcc, assemble, disassemble, cc_harness

XSUBS

The C and CC backends can successfully compile some perl programs which