xsubpp treats invalid (indented) cpp directives as comments

[p5sagit/p5-mst-13.2.git] / ext / B / NOTES

C backend invocation
	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
	-v		Verbose (currently gives a few compilation statistics)
	--		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.
	-D		Debug options (concat or separate flags like perl -D)
		o	OPs, prints each OP as it's processed
		c	COPs, prints COPs as processed (incl. file & line num)
		A	prints AV information on saving
		C	prints CV information on saving
		M	prints MAGIC information on saving
	-f		Force optimisations on or off one at a time.
		cog	Copy-on-grow: PVs declared and initialised statically
		no-cog	No copy-on-grow
	-On		Optimisation level (n = 0, 1, 2, ...). -O means -O1.
			Currently, -O1 and higher set -fcog.

Examples
	perl -MO=C foo.pl > foo.c
	perl cc_harness -o foo foo.c

	perl -MO=C,-v,-DcA bar.pl > /dev/null

CC backend invocation
	If there are any non-option arguments, they are taken to be names of
	subs to be saved. Without extra arguments, it saves the main program.
	-ofilename	Output to filename instead of STDOUT
	--		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.
	-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.
	-pn		Generate code for perl patchlevel n (e.g. 3 or 4).
			The default is to generate C code which will link
			with the currently executing version of perl.
			running the perl compiler.
	-D		Debug options (concat or separate flags like perl -D)
		r	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).
		O	Outputs each OP as it's compiled
		s	Outputs the contents of the shadow stack at each OP
		p	Outputs the contents of the shadow pad of lexicals as
			it's loaded for each sub or the main program.
		q	Outputs the name of each fake PP function in the queue
			as it's about to processes.
		l	Output the filename and line number of each original
			line of Perl code as it's processed (pp_nextstate).
		t	Outputs timing information of compilation stages
	-f		Force optimisations on or off one at a time.
		[
		cog	Copy-on-grow: PVs declared and initialised statically
		no-cog	No copy-on-grow
		These two not in CC yet.
		]
		freetmps-each-bblock	Delays FREETMPS from the end of each
					statement to the end of the each basic
					block.
		freetmps-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.
		omit-taint		Omits generating code for handling
					perl's tainting mechanism.
	-On		Optimisation level (n = 0, 1, 2, ...). -O means -O1.
			Currently, -O1 sets -ffreetmps-each-bblock and -O2
			sets -ffreetmps-each-loop.

Example
	perl -MO=CC,-O2,-ofoo.c foo.pl
	perl cc_harness -o foo foo.c

	perl -MO=CC,-mFoo,-oFoo.c Foo.pm
	perl cc_harness -shared -c -o Foo.so Foo.c


Bytecode backend invocation

	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.
	--		Force end of options.
	-f		Force optimisations on or off one at a time.
			Each can be preceded by no- to turn the option off.
		compress-nullops
			Only fills in the necessary fields of ops which have
			been optimised away by perl's internal compiler.
		omit-sequence-numbers
			Leaves out code to fill in the op_seq field of all ops
			which is only used by perl's internal compiler.
		bypass-nullops
			If op->op_next ever points to a NULLOP, replaces the
			op_next field with the first non-NULLOP in the path
			of execution.
		strip-syntax-tree
			Leaves out code to fill in the pointers which link the
			internal syntax tree together. They're not needed at
			run-time but leaving them out will make it impossible
			to recompile or disassemble the resulting program.
			It will also stop "goto label" statements from working.
	-On		Optimisation level (n = 0, 1, 2, ...). -O means -O1.
			-O1 sets -fcompress-nullops -fomit-sequence numbers.
			-O6 adds -fstrip-syntax-tree.
	-D		Debug options (concat or separate flags like perl -D)
		o	OPs, prints each OP as it's processed.
		b	print debugging information about bytecompiler progress
		a	tells the assembler to include source assembler lines
			in its output as bytecode comments.
		C	prints each CV taken from the final symbol tree walk.
	-S		Output assembler source rather than piping it
			through the assembler and outputting bytecode.
	-m		Compile as a module rather than a standalone program.
			Currently this just means that the bytecodes for
			initialising main_start, main_root and curpad are
			omitted.

Example
	perl -MO=Bytecode,-O6,-o,foo.plc foo.pl

	perl -MO=Bytecode,-S foo.pl > foo.S
	assemble foo.S > foo.plc
	byteperl foo.plc

	perl -MO=Bytecode,-m,-oFoo.pmc Foo.pm

Backends for debugging
	perl -MO=Terse,exec foo.pl
	perl -MO=Debug bar.pl

O module
	Used with "perl -MO=Backend,foo,bar prog.pl" to invoke the backend
	B::Backend with options foo and bar. O invokes the sub
	B::Backend::compile() with arguments foo and bar at BEGIN time.
	That compile() sub must do any inital argument processing replied.
	If unsuccessful, it should return a string which O arranges to be
	printed as an error message followed by a clean error exit. In the
	normal case where any option processing in compile() is successful,
	it should return a sub ref (usually a closure) to perform the
	actual compilation. When O regains control, it ensures that the
	"-c" option is forced (so that the program being compiled doesn't
	end up running) and registers a CHECK block to call back the sub ref
	returned from the backend's compile(). Perl then continues by
	parsing prog.pl (just as it would with "perl -c prog.pl") and after
	doing so, assuming there are no parse-time errors, the CHECK block
	of O gets called and the actual backend compilation happens. Phew.