view release on metacpan or  search on metacpan

README.alpha  view on Meta::CPAN

    make
and you can then use
    perl -Iblib/arch -MO=foo bar
to use the compiler modules (see later for details).
If you need/want instead to make a statically linked perl which
contains the appropriate modules, then type
    make perl
    make byteperl
and you can then use
    ./perl -MO=foo bar
to use the compiler modules.    
In both cases, the byteperl executable is required for running standalone
bytecode programs. It is *not* a standard perl+XSUB perl executable.

USAGE

As of the alpha3 release, the Bytecode, C and CC backends are now all
functional enough to compile almost the whole of the main perl test
suite. In the case of the CC backend, any failures are all due to
differences and/or known bugs documented below. See the file TESTS.
In the following examples, you'll need to replace "perl" by
    perl -Iblib/arch
if you have built the extensions for a dynamic loading platform but
haven't installed the extensions completely. You'll need to replace
"perl" by
    ./perl
if you have built the extensions into a statically linked perl binary.

(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 compiler backend, you need to tell the
compiler when you're using int or double variables so that it can
optimise appropriately (although this part of the compiler is the most
buggy). You currently do that 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 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. But, hey, this is an alpha release 
so you knew that anyway. See the XSUB section lower down for information 
about compiling programs which use XSUBs.

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. For example, with Digital UNIX, do something like
    ld -shared -o libperl.so -all libperl.a -none -lc
and with Linux/ELF, rebuild the perl .c files with -fPIC (and I
also suggest -fomit-frame-pointer for Linux on Intel architetcures),
do "make libperl.a" and then do
    gcc -shared -Wl,-soname,libperl.so.5 -o libperl.so.5.3 `ar t libperl.a`
and then
    # cp libperl.so.5.3 /usr/lib
    # cd /usr/lib
    # ln -s libperl.so.5.3 libperl.so.5
    # ln -s libperl.so.5 libperl.so
    # ldconfig
When you compile perl executables with cc_harness, append -L/usr/lib
otherwise the -L for the perl source directory will override it. For
example,
    perl -Iblib/arch -MO=CC,-O2,-ofoo3.c foo3.bench
    perl cc_harness -o foo3 -O2 foo3.c -L/usr/lib
    ls -l foo3
    -rwxr-xr-x   1 mbeattie xzdg        11218 Jul  1 15:28 foo3
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 foo.pl
To run the resulting bytecode file foo as a standalone program, you
use the program byteperl which should have been built along with the
extensions.
    ./byteperl foo
Any extra arguments are passed in as @ARGV; they are not interpreted
as perl options. If you want to load chunks of bytecode into an already
running perl program then use the -m option and investigate the
byteload_fh and byteload_string functions exported by the B module.
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).