NOTES 8.4 KB

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