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