NAME

SYNOPSIS

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

DESCRIPTION

OPTIONS

-ofilename

Output to filename instead of STDOUT

-c

Check and abort.

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

-v

Verbose compilation (prints a few compilation stages).

--

Force end of options

-uPackname

Force apparently unused subs from package Packname 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.

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

-mModulename

Instead of generating source for a runnable executable, generate source for an XSUB module. The boot_Modulename function (which DynaLoader can look for) does the appropriate initialisation and runs the main part of the Perl source that is being compiled.

-nInitname

Provide a different init name for additional objects added via cmdline.

-strict

With a DEBUGGING perl compile-time errors for range and flip without compile-time context are only warnings. With "-strict" these warnings are fatal, otherwise only run-time errors occur.

-On

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

The following B::C optimisations are applied automatically:

optimize_warn_sv save_data_fh av-init2|av_init save_sig destruct pv_copy_on_grow

-O1 sets -ffreetmps-each-bblock.

-O2 adds -ffreetmps-each-loop, "-faelem" and -fno-destruct from B::C.

The following options must be set explicitly:

  B<-fno-taint> or B<-fomit-taint>,

  B<-fslow-signals>,

  B<-no-autovivify>,

  B<-fno-magic>.
    

-f"OPTIM"

Force optimisations on or off one at a time. Unknown optimizations are passed down to B::C.

-ffreetmps-each-bblock

Delays FREETMPS from the end of each statement to the end of the each basic block.

Enabled with -O1.

-ffreetmps-each-loop

Delays FREETMPS from the end of each statement to the end of the group of basic blocks forming a loop. At most one of the freetmps-each-* options can be used.

Enabled with -O2.

-faelem

Enable array element access optimizations, allowing unchecked fast access under certain circumstances.

Enabled with -O2 and not-threaded perls only.

-fno-inline-ops

Do not inline calls to certain small pp ops.

Most of the inlinable ops were already inlined. Turns off inlining for some new ops.

AUTOMATICALLY inlined:

pp_null pp_stub pp_unstack pp_and pp_andassign pp_or pp_orassign pp_cond_expr pp_padsv pp_const pp_nextstate pp_dbstate pp_rv2gv pp_sort pp_gv pp_gvsv pp_aelemfast pp_ncmp pp_add pp_subtract pp_multiply pp_divide pp_modulo pp_left_shift pp_right_shift pp_i_add pp_i_subtract pp_i_multiply pp_i_divide pp_i_modulo pp_eq pp_ne pp_lt pp_gt pp_le pp_ge pp_i_eq pp_i_ne pp_i_lt pp_i_gt pp_i_le pp_i_ge pp_scmp pp_slt pp_sgt pp_sle pp_sge pp_seq pp_sne pp_sassign pp_preinc pp_pushmark pp_list pp_entersub pp_formline pp_goto pp_enterwrite pp_leavesub pp_leavewrite pp_entergiven pp_leavegiven pp_entereval pp_dofile pp_require pp_entertry pp_leavetry pp_grepstart pp_mapstart pp_grepwhile pp_mapwhile pp_return pp_range pp_flip pp_flop pp_enterloop pp_enteriter pp_leaveloop pp_next pp_redo pp_last pp_subst pp_substcont

DONE with -finline-ops:

pp_enter pp_reset pp_regcreset pp_stringify

TODO with -finline-ops:

pp_anoncode pp_wantarray pp_srefgen pp_refgen pp_ref pp_trans pp_schop pp_chop pp_schomp pp_chomp pp_not pp_sprintf pp_anonlist pp_shift pp_once pp_lock pp_rcatline pp_close pp_time pp_alarm pp_av2arylen: no lvalue, pp_length: no magic

-fomit-taint

Omits generating code for handling perl's tainting mechanism.

-fslow-signals

Add PERL_ASYNC_CHECK after every op as in the old Perl runloop before 5.13.

perl "Safe signals" check the state of incoming signals after every op. See <http://perldoc.perl.org/perlipc.html#Deferred-Signals-(Safe-Signals)> We trade safety for more speed and delay the execution of non-IO signals (IO signals are already handled in PerlIO) from after every single Perl op to the same ops as used in 5.14.

Only with -fslow-signals we get the old slow and safe behaviour.

-fno-name-magic

With the default "-fname-magic" we infer the SCALAR type for specially named locals vars and most ops use C vars then, not the perl vars. Arithmetic and comparison is inlined. Scalar magic is bypassed.

With "-fno-name-magic" do not infer a local variable type from its name:

  B<_i> suffix for int, B<_d> for double/num, B<_ir> for register int
    

See the experimental "-ftype-attr" type attributes. Currently supported are int and num only. See </load_pad>.

-ftype-attr (DOES NOT WORK YET)

Experimentally support type attributes for int and num, SCALAR only so far. For most ops new C vars are used then, not the fat perl vars. Very awkward to use until the basic type classes are supported from within core or use types.

Enabled with -O2. See TYPES and </load_pad>.

-fno-autovivify

Do not vivify array and soon also hash elements when accessing them. Beware: Vivified elements default to undef, unvivified elements are invalid.

This is the same as the pragma "no autovivification" and allows very fast array accesses, 4-6 times faster, without the overhead of autovivification.

-fno-magic

Assume certain data being optimized is never tied or is holding other magic. This mainly holds for arrays being optimized, but in the future hashes also.

-D

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.

-Dr

Writes debugging output to STDERR just as it's about to write to the program's runtime (otherwise writes debugging info as comments in its C output).

-DO

Outputs each OP as it's compiled

-DT

Outputs the contents of the stack at each OP. Values are B::Stackobj objects.

-Dc

Outputs the contents of the loop context stack, the @cxstack.

-Dw

Outputs the contents of the shadow stack at each OP.

-Da

Outputs the contents of the shadow pad of lexicals as it's loaded for each sub or the main program.

-Dq

Outputs the name of each fake PP function in the queue as it's about to process it.

-Dl

Output the filename and line number of each original line of Perl code as it's processed ("pp_nextstate").

-Dt

Outputs timing information of compilation stages.

-DF

Add Flags info to the code.

NOTABLE FUNCTIONS

save_or_restore_lexical_state

Missing flags are regenerated by loading values.

Added flags must are removed; otherwise the compiler would be too optimistic, hence generating code which doesn't match state of the other execution paths.

EXAMPLES

        perl -MO=CC,-O2,-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.

        # create a shared XS module
        perl -MO=CC,-mFoo,-oFoo.c Foo.pm
        perl cc_harness -shared -c -o Foo.so Foo.c

        # side-effects just for the types and attributes
        perl -MB::CC -e'my int $i:unsigned; ...'

TYPES

Deprecated are inferred types via the names of locals, with '_i', '_d' suffix and an optional 'r' suffix for register allocation.

  C<my ($i_i, $j_ir, $num_d);>

Planned type attributes are int, num, str, unsigned, ro / const.

The attributes are perl attributes, and "int|num|str" are either compiler classes or hints for more allowed types.

  C<my int $i :num;>  declares a NV with SVf_IOK. Same as C<my $i:int:double;>
  C<my int $i;>          declares an IV. Same as C<my $i:int;>
  C<my int $i :str;>  declares a PVIV. Same as C<my $i:int:string;>

  C<my int @array :unsigned = (0..4);> will be used as c var in faster arithmetic and cmp.
                                       With :const or :ro even more.
  C<my str %hash :const
    = (foo => 'foo', bar => 'bar');> declare string values,
                                     generate as read-only perfect hash.

:unsigned is valid for int only and declares an UV.

:register denotes optionally a short and hot life-time.

:temporary are usually generated internally, nameless lexicals. They are more aggressivly destroyed and ignored.

:ro or :const throw a compile-time error on write access and may optimize the internal structure of the variable. We don't need to write back the variable to perl (lexical write_back).

STATUS

OK (classes only):

  my int $i;
  my num $d;

NOT YET OK (attributes):

  my int $i :register;
  my $i :int;
  my $const :int:const;
  my $uv :int:unsigned;

ISSUES

This does not work with pure perl, unless you "use B::CC" or "use types" or implement the classes and attribute type stubs in your code, "sub Mypkg::MODIFY_SCALAR_ATTRIBUTES {}" and "sub Mypkg::FETCH_SCALAR_ATTRIBUTES {}". (TODO: empty should be enough to be detected by the compiler.)

Compiled code pulls in the magic MODIFY_SCALAR_ATTRIBUTES and FETCH_SCALAR_ATTRIBUTES functions, even if they are used at compile time only.

Using attributes adds an import block to your code.

Up until 5.20 only our variable attributes are checked at compile-time, my variables attributes at run-time only, which is too late for the compiler. Perl attributes need to be fixed for types hints by adding "CHECK_SCALAR_ATTRIBUTES".

FUTURE

We should be able to support types on ARRAY and HASH. For arrays also sizes to omit bounds-checking.

  my int @array; # array of ints, faster magic-less access esp. in inlined arithmetic and cmp.
  my str @array : const = qw(foo bar);   # compile-time error on write. no lexical write_back

  my int $hash = {"1" => 1, "2" => 2};   # int values, type-checked on write my
  str %hash1 : const = (foo => 'bar');   # string keys only => maybe gperf
                                         # compile-time error on write

Typed hash keys are always strings, as array keys are always int. Only the values are typed.

We should be also able to add type attributes for functions and methods, i.e. for argument and return types. See types and <http://blogs.perl.org/users/rurban/2011/02/use-types.html>

BUGS

DIFFERENCES

    sub skip_on_odd { next NUMBER if $_[0] % 2 }
    NUMBER: for ($i = 0; $i < 5; $i++) {
        skip_on_odd($i);
        print $i;
    }

    024

    @a = (4,6,1,0,0,1);
    sub range { (shift @a)..(shift @a) }
    print range();
    while (@a) { print scalar(range()) }

    456123E0

AUTHORS