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

-c

Check and abort.

Compiles and prints only warnings, but does not emit C code.

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

-UPackage "unuse" skip Package

Ignore all subs from Package to be compiled.

Certain packages might not be needed at run-time, even if the pessimistic walker detects it.

-staticxs

Dump a list of bootstrapped XS package names to outfile.lst needed for perlcc --staticxs. 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.

-DP

Extra PV information on saving. (static, len, hek, fake_off, ...)

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

-DR

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

-Dr

Writes debugging output to STDERR and to the program's generated C file. Otherwise writes debugging info to STDERR only.

-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 (Ignored)

Future flag to enable Copy-on-grow, i.e Copy-on-write, when perl will store the COWREFCNT in a seperate field and not in the string buffer.

Some strings are declared and initialised statically independent of -fcog, see -fconst-strings instead.

-fav-init

Faster pre-initialization of AVs (arrays and pads). Also used if -fav-init2 is used and independent_comalloc() is not detected.

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

-fppaddr

Optimize the initialization of op_ppaddr.

Enabled with -O1.

-fwarn-sv

Use static initialization for cop_warnings. Automatically disabled for MSVC 5.

Disable with -fno-warn-sv.

-fro-inc

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

This forbids run-time extends of INC path strings, the run-time will crash then.

It will also skip storing string values of internal regexp capture groups $1 - $9, which were used internally by the compiler or some module. They are considered volatile.

Enabled with -O2.

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

-fcow

Enforce static COW strings since 5.18 for most strings.

Enabled with -O2 since 5.20.

-fconst-strings

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

Enabled with -O3.

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

-fno-walkall uses the simple old algorithm to detect which packages needs to be stored. -fwalkall was introduced to catch previously uncompiled packages for computed methods or undetected deeper run-time dependencies.

-fno-save-sig-hash

Disable compile-time modifications to the %SIG hash.

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

Enabled with -O3.

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

Enabled with -O3.

-fstash

Add dynamic creation of stashes, which are nested hashes of symbol tables, names ending with ::, starting at %main::.

These are rarely needed, sometimes for checking of existance of packages, which could be better done by checking %INC, and cost about 10% space and startup-time.

If an explicit stash member or the stash itself %package:: is used in the source code, the requested stash member(s) is/are automatically created.

-fno-stash is the default.

-fno-delete-pkg

Do not delete compiler-internal and dependent packages which appear to be nowhere used automatically. This might miss run-time called stringified methods. See B::C::Config for @deps which packages are affected.

-fdelete-pkg is the default.

-fuse-script-name

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

Not enabled with any -O option.

-fno-dyn-padlist

Disable dynamic padlists since 5.17.6. Dynamic padlists are needed to prevent from cv_undef crashes on static padlists when cleaning up the stack on non-local exits, like die or exit.

All functions in END blocks and all Attribute::Handler function padlists are automatically dynamic.

Enabled with -O4.

-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-init2/-fav-init, -fppaddr and -fwarn-sv.

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

-O2

Enable -O1 plus -fro-inc, -fsave-data and fcow.

-O3

Enable -O2 plus -fno-destruct and -fconst-strings.

-O4

Enable -O3 plus -fcop and -fno-dyn-padlist. Very unsafe, rarely works, 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

-cross=pathto/config.sh

Use a different %Config from another config.sh for cross-compilation. %INC will still have the host paths, but @INC and $^X the target paths. See B::C::Config.

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

CAVEAT

With 5.6 it is not possible to use the __DATA__ filehandle, because compatible access via PerlIO::scalar was added with 5.8.1

It is generally not possible to restore all of the compiled BEGIN-time state. Esp. problematic are non-standard filehandles (i.e. fd>2), process ids, environment specific knowledge, because only with the compiler BEGIN blocks are not executed in the client environment.

The compiler produces some warnings, which might need source code changes or changed compiler options.

Warning: Problem with require "$name" - $INC{file.pm}

Dynamic load of $name did not add the expected %INC key.

Warning: C.xs PMOP missing for QR

In an initial C.xs runloop all QR regex ops are stored, so that they can matched later to PMOPs.

Warning: DynaLoader broken with 5.15.2-5.15.3.

[perl #100138] DynaLoader symbols were XS_INTERNAL. Strict linking could not resolve it. Usually libperl was patched to overcome this for these two versions. Setting the environment variable NO_DL_WARN=1 omits this warning.

Warning: __DATA__ handle $fullname not stored. Need -O2 or -fsave-data.

Since processing the __DATA__ filehandle involves some overhead, requiring PerlIO::scalar with all its dependencies, you must use -O2 or -fsave-data.

Warning: Write BEGIN-block $fullname to FileHandle $iotype \&$fd

Critical problem. This must be fixed in the source.

Warning: Read BEGIN-block $fullname from FileHandle $iotype \&$fd

Critical problem. This must be fixed in the source.

Warning: -o argument ignored with -c

-c does only check, but not accumulate C output lines.

Warning: unresolved $section symbol s\\xxx

This symbol was not resolved during compilation, and replaced by 0.

With B::C this is most likely a critical internal compiler bug, esp. if in an op section. See [issue #110].

With B::CC it can be caused by valid optimizations, e.g. when op->next pointers were inlined or inlined GV or CONST ops were optimized away.

BUGS

Current status: A few known bugs, but usable in production

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

>=5.10: Attribute::Handlers and run-time attributes @- (#281) compile-time perlio layers run-time loading of DynaLoader packages which use AutoLoad i.e. BSD::Resource. (#308) format STDOUT or STDERR (#285)

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.