NAME

B::C - Perl compiler's C backend

SYNOPSIS

perl -MO=C[,OPTIONS] foo.pl

DESCRIPTION

This compiler backend takes Perl source and generates C source code corresponding to the internal structures that perl uses to run your program. When the generated C source is compiled and run, it cuts out the time which perl would have taken to load and parse your program into its internal semi-compiled form. That means that compiling with this backend will not help improve the runtime execution speed of your program but may improve the start-up time. Depending on the environment in which your program runs this may be either a help or a hindrance.

OPTIONS

If there are any non-option arguments, they are taken to be names of objects to be saved (probably doesn't work properly yet). Without extra arguments, it saves the main program.

-ofilename

Output to filename instead of STDOUT

-mPackagename (NYI)

Prepare to compile a module with all dependent code to a single shared library rather than to standalone program.

Currently this just means that the code for initialising main_start, main_root and curpad are omitted. The .pm stub to bootstrap the shared lib is not generated. This option should be used via perlcc -m.

Not yet implemented.

-ninit_name

Default: "perl_init" and "init_module"

-v

Verbose compilation. Currently gives a few compilation statistics.

--

Force end of options

-uPackage "use Package"

Force all subs from Package to be compiled. This allows programs to use eval "foo()" even when sub foo is never seen to be used at compile time. The down side is that any subs which really are never used also have code generated. This option is necessary, for example, if you have a signal handler foo which you initialise with $SIG{BAR} = "foo". A better fix, though, is just to change it to $SIG{BAR} = \&foo. You can have multiple -u options. The compiler tries to figure out which packages may possibly have subs in which need compiling but the current version doesn't do it very well. In particular, it is confused by nested packages (i.e. of the form A::B) where package A does not contain any subs.

-staticxs

Dump a list of bootstrapped XS package names to outfile.lst needed for perlcc --staticxs and add code to DynaLoader to add the .so/.dll path to PATH.

-D[OPTIONS]

Debug options, concatenated or separate flags like perl -D. Verbose debugging options are crucial, because the interactive debugger Od adds a lot of ballast to the resulting code.

-Dfull

Enable all full debugging, as with -DoOcAHCMGSpWF. All but -Du.

-Do

All Walkop'ed OPs

-DO

OP Type,Flags,Private

-DS

Scalar SVs, prints SV/RE/RV information on saving.

-Dc

COPs, prints COPs as processed (incl. file & line num)

-DA

prints AV information on saving.

-DH

prints HV information on saving.

-DC

prints CV information on saving.

-DG

prints GV information on saving.

-DM

prints MAGIC information on saving.

-Dp

prints cached package information, if used or not.

-Ds

prints all compiled sub names, optionally with " not found".

-DF

Add Flags info to the code.

-DW

Together with -Dp also prints every walked package symbol.

-Du

do not print -D information when parsing for the unused subs.

-fOPTIM

Force options/optimisations on or off one at a time. You can explicitly disable an option using -fno-option. All options default to disabled.

-fcog

Copy-on-grow: PVs declared and initialised statically. Does not work yet with Perl 5.10 and higher unless -fno-destruct is added.

Enabled with -O1.

-fconst-strings

Declares readonly strings as const. Enables -fcog. Note that readonly strings in eval'd string code will cause a run-time failure.

Enabled with -O3.

-fsave-data

Save package::DATA filehandles ( only available with PerlIO ). Does not work yet on Perl 5.6, 5.12 and non-threaded 5.10, and is enabled automatically where it is known to work.

Enabled with -O3.

-fppaddr

Optimize the initialization of op_ppaddr.

Enabled with -O2.

-fwarn-sv

Optimize the initialization of cop_warnings.

Enabled with -O2.

-fav-init

Faster pre-initialization of AVs (arrays and pads)

Enabled with -O1.

-fav-init2

Even more faster pre-initialization of AVs with independent_comalloc() if supported. Excludes -fav_init if so; uses -fav_init if independent_comalloc() is not supported.

independent_comalloc() is recommended from ptmalloc3, but also included in ptmalloc, dlmalloc and nedmalloc. Download ptmalloc3 here: http://www.malloc.de/en/ Note: independent_comalloc() is not included in google-perftools tcmalloc.

Enabled with -O2.

-fro-inc

Set read-only @INC and %INC pathnames (-fconst-string, not the AV) and also curpad names and symbols, to store them const and statically, not via malloc at run-time.

This forbids run-time extends of curpad syms, names and INC strings, the run-time will crash then.

Enabled with -O2.

-fno-destruct

Does no global perl_destruct() at the end of the process, leaving the memory cleanup to operating system.

This will cause problems if used embedded or as shared library/module, but not in long-running processes.

This helps with destruction problems of static data in the default perl destructor, and enables -fcog since 5.10.

Enabled with -O3.

-fno-fold (since 5.14)

m//i since 5.13.10 requires the whole unicore/To/Fold table in memory, which is about 1.6MB on 32-bit. In CORE this is demand-loaded from utf8.pm.

If you are sure not to use or require any case-insensitive matching you can strip this table from memory with -fno-fold.

Not enabled with any -O option.

-fno-warnings (since 5.14)

Run-time warnings since 5.13.5 require some warnings::register_categories in memory, which is about 68kB on 32-bit. In CORE this is demand-loaded from warnings.pm.

You can strip this table from memory with -fno-warnings.

Not enabled with any -O option.

-fuse-script-name

Use the script name instead of the program name as $0.

Not enabled with any -O option.

-fsave-sig-hash

Save compile-time modifications to the %SIG hash.

Enabled with -O3.

-fcop

DO NOT USE YET!

Omit COP info (nextstate without labels, unneeded NULL ops, files, linenumbers) for ~10% faster execution and less space, but warnings and errors will have no file and line infos.

It will most likely not work yet. (was -fbypass-nullops in earlier compilers)

Enabled with -O4.

-On

Optimisation level (n = 0, 1, 2, 3, 4). -O means -O1.

-O0

Disable all optimizations.

-O1

Enable -fcog, -fav-init.

Note that -fcog without -fno-destruct will be disabled >= 5.10.

-O2

Enable -O1 plus -fppaddr, -fwarn-sv, -fav-init2, -fro-inc.

-O3

Enable -O2 plus -fsave-sig-hash, -fsave-data, -fno-destruct, -fconst-strings

-O4

Enable -O3 plus -fcop. Very unsafe, 10% faster, 10% smaller.

-llimit

"line length limit".

Some C compilers impose an arbitrary limit on the length of string constants (e.g. 2048 characters for Microsoft Visual C++). -l2048 tells the C backend not to generate string literals exceeding that limit.

-e ARG

Evaluate ARG at startup

EXAMPLES

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

Note that cc_harness lives in the B subdirectory of your perl library directory. The utility called perlcc may also be used to help make use of this compiler.

perlcc foo.pl

perl -MO=C,-v,-DcA,-l2048 bar.pl > /dev/null

BUGS

Current status: A few known bugs.

5.6: reading from __DATA__ handles (15) AUTOLOAD xsubs (27)

>=5.10: &XSLoader::load sometimes missing reading from __DATA__ handles (15) non-threaded handling npP magic for shared threaded variables (41-43) destruction of variables in END blocks

AUTHOR

Malcolm Beattie MICB at cpan.org (1996-1998, retired), Nick Ing-Simmons <nik at tiuk.ti.com> I(1998-1999), Vishal Bhatia <vishal at deja.com> I(1999), Gurusamy Sarathy <gsar at cpan.org> I(1998-2001), Mattia Barbon <mbarbon at dsi.unive.it> I(2002), Reini Urban perl-compiler@googlegroups.com I(2008-)

SEE ALSO

perlcompiler for a general overview, B::CC for the optimising C compiler, B::Bytecode + ByteLoader for the bytecode compiler, Od for source level debugging in the B::Debugger, illguts for the illustrated Perl guts, perloptree for the Perl optree.