contrib/perl5/ext/B/NOTES

   1 C backend invocation
   2         If there are any non-option arguments, they are taken to be
   3         names of objects to be saved (probably doesn't work properly yet).
   4         Without extra arguments, it saves the main program.
   5         -ofilename      Output to filename instead of STDOUT
   6         -v              Verbose (currently gives a few compilation statistics)
   7         --              Force end of options
   8         -uPackname      Force apparently unused subs from package Packname to
   9                         be compiled. This allows programs to use eval "foo()"
  10                         even when sub foo is never seen to be used at compile
  11                         time. The down side is that any subs which really are
  12                         never used also have code generated. This option is
  13                         necessary, for example, if you have a signal handler
  14                         foo which you initialise with $SIG{BAR} = "foo".
  15                         A better fix, though, is just to change it to
  16                         $SIG{BAR} = \&foo. You can have multiple -u options.
  17         -D              Debug options (concat or separate flags like perl -D)
  18                 o       OPs, prints each OP as it's processed
  19                 c       COPs, prints COPs as processed (incl. file & line num)
  20                 A       prints AV information on saving
  21                 C       prints CV information on saving
  22                 M       prints MAGIC information on saving
  23         -f              Force optimisations on or off one at a time.
  24                 cog     Copy-on-grow: PVs declared and initialised statically
  25                 no-cog  No copy-on-grow
  26         -On             Optimisation level (n = 0, 1, 2, ...). -O means -O1.
  27                         Currently, -O1 and higher set -fcog.
  28
  29 Examples
  30         perl -MO=C foo.pl > foo.c
  31         perl cc_harness -o foo foo.c
  32
  33         perl -MO=C,-v,-DcA bar.pl > /dev/null
  34
  35 CC backend invocation
  36         If there are any non-option arguments, they are taken to be names of
  37         subs to be saved. Without extra arguments, it saves the main program.
  38         -ofilename      Output to filename instead of STDOUT
  39         --              Force end of options
  40         -uPackname      Force apparently unused subs from package Packname to
  41                         be compiled. This allows programs to use eval "foo()"
  42                         even when sub foo is never seen to be used at compile
  43                         time. The down side is that any subs which really are
  44                         never used also have code generated. This option is
  45                         necessary, for example, if you have a signal handler
  46                         foo which you initialise with $SIG{BAR} = "foo".
  47                         A better fix, though, is just to change it to
  48                         $SIG{BAR} = \&foo. You can have multiple -u options.
  49         -mModulename    Instead of generating source for a runnable executable,
  50                         generate source for an XSUB module. The
  51                         boot_Modulename function (which DynaLoader can look
  52                         for) does the appropriate initialisation and runs the
  53                         main part of the Perl source that is being compiled.
  54         -pn             Generate code for perl patchlevel n (e.g. 3 or 4).
  55                         The default is to generate C code which will link
  56                         with the currently executing version of perl.
  57                         running the perl compiler.
  58         -D              Debug options (concat or separate flags like perl -D)
  59                 r       Writes debugging output to STDERR just as it's about
  60                         to write to the program's runtime (otherwise writes
  61                         debugging info as comments in its C output).
  62                 O       Outputs each OP as it's compiled
  63                 s       Outputs the contents of the shadow stack at each OP
  64                 p       Outputs the contents of the shadow pad of lexicals as
  65                         it's loaded for each sub or the main program.
  66                 q       Outputs the name of each fake PP function in the queue
  67                         as it's about to processes.
  68                 l       Output the filename and line number of each original
  69                         line of Perl code as it's processed (pp_nextstate).
  70                 t       Outputs timing information of compilation stages
  71         -f              Force optimisations on or off one at a time.
  72                 [
  73                 cog     Copy-on-grow: PVs declared and initialised statically
  74                 no-cog  No copy-on-grow
  75                 These two not in CC yet.
  76                 ]
  77                 freetmps-each-bblock    Delays FREETMPS from the end of each
  78                                         statement to the end of the each basic
  79                                         block.
  80                 freetmps-each-loop      Delays FREETMPS from the end of each
  81                                         statement to the end of the group of
  82                                         basic blocks forming a loop. At most
  83                                         one of the freetmps-each-* options can
  84                                         be used.
  85                 omit-taint              Omits generating code for handling
  86                                         perl's tainting mechanism.
  87         -On             Optimisation level (n = 0, 1, 2, ...). -O means -O1.
  88                         Currently, -O1 sets -ffreetmps-each-bblock and -O2
  89                         sets -ffreetmps-each-loop.
  90
  91 Example
  92         perl -MO=CC,-O2,-ofoo.c foo.pl
  93         perl cc_harness -o foo foo.c
  94
  95         perl -MO=CC,-mFoo,-oFoo.c Foo.pm
  96         perl cc_harness -shared -c -o Foo.so Foo.c
  97
  98
  99 Bytecode backend invocation
 100
 101         If there are any non-option arguments, they are taken to be
 102         names of objects to be saved (probably doesn't work properly yet).
 103         Without extra arguments, it saves the main program.
 104         -ofilename      Output to filename instead of STDOUT.
 105         --              Force end of options.
 106         -f              Force optimisations on or off one at a time.
 107                         Each can be preceded by no- to turn the option off.
 108                 compress-nullops
 109                         Only fills in the necessary fields of ops which have
 110                         been optimised away by perl's internal compiler.
 111                 omit-sequence-numbers
 112                         Leaves out code to fill in the op_seq field of all ops
 113                         which is only used by perl's internal compiler.
 114                 bypass-nullops
 115                         If op->op_next ever points to a NULLOP, replaces the
 116                         op_next field with the first non-NULLOP in the path
 117                         of execution.
 118                 strip-syntax-tree
 119                         Leaves out code to fill in the pointers which link the
 120                         internal syntax tree together. They're not needed at
 121                         run-time but leaving them out will make it impossible
 122                         to recompile or disassemble the resulting program.
 123                         It will also stop "goto label" statements from working.
 124         -On             Optimisation level (n = 0, 1, 2, ...). -O means -O1.
 125                         -O1 sets -fcompress-nullops -fomit-sequence numbers.
 126                         -O6 adds -fstrip-syntax-tree.
 127         -D              Debug options (concat or separate flags like perl -D)
 128                 o       OPs, prints each OP as it's processed.
 129                 b       print debugging information about bytecompiler progress
 130                 a       tells the assembler to include source assembler lines
 131                         in its output as bytecode comments.
 132                 C       prints each CV taken from the final symbol tree walk.
 133         -S              Output assembler source rather than piping it
 134                         through the assembler and outputting bytecode.
 135         -m              Compile as a module rather than a standalone program.
 136                         Currently this just means that the bytecodes for
 137                         initialising main_start, main_root and curpad are
 138                         omitted.
 139
 140 Example
 141         perl -MO=Bytecode,-O6,-o,foo.plc foo.pl
 142
 143         perl -MO=Bytecode,-S foo.pl > foo.S
 144         assemble foo.S > foo.plc
 145         byteperl foo.plc
 146
 147         perl -MO=Bytecode,-m,-oFoo.pmc Foo.pm
 148
 149 Backends for debugging
 150         perl -MO=Terse,exec foo.pl
 151         perl -MO=Debug bar.pl
 152
 153 O module
 154         Used with "perl -MO=Backend,foo,bar prog.pl" to invoke the backend
 155         B::Backend with options foo and bar. O invokes the sub
 156         B::Backend::compile() with arguments foo and bar at BEGIN time.
 157         That compile() sub must do any inital argument processing replied.
 158         If unsuccessful, it should return a string which O arranges to be
 159         printed as an error message followed by a clean error exit. In the
 160         normal case where any option processing in compile() is successful,
 161         it should return a sub ref (usually a closure) to perform the
 162         actual compilation. When O regains control, it ensures that the
 163         "-c" option is forced (so that the program being compiled doesn't
 164         end up running) and registers an END block to call back the sub ref
 165         returned from the backend's compile(). Perl then continues by
 166         parsing prog.pl (just as it would with "perl -c prog.pl") and after
 167         doing so, assuming there are no parse-time errors, the END block
 168         of O gets called and the actual backend compilation happens. Phew.