=head1 Running perl6

=head1 Synopsis

Please run B<perl6 --help> to see actual options.

They are currently changing on demand, there are a lot of debug options,
so keeping this document in sync is currently not worth the effort --
sorry.

Run B<perl6 --test> for a full test run. If everything succeeds - fine.
If not, read on. If you want to know more, read on ;-)


=head1 Getting started

For a quick test, if everything is ok, try a one liner:

	perl6 -vwk -e'print(qq(Hello perl6\n))'

You should see the individual compilation steps and finally the output
of above program.

If that fails, there are currently 3 steps that might be the culprit:

=over 4

=item P6C -- the perl6 compiler

=item imcc -- the intermediate compiler

=item parrot -- the parrot interpreter

=back

=head1 Individual steps

=head2 P6C

The perl6 compiler needs an uptodate grammar to work correctly.  If
you have modified the grammar in P6C/Parser.pm, you will need to make
sure Perl6grammar.pm is regenerated by running

	perl6 --force-grammar -e'print qq(ok\n)' -vwk

or

	rm Perl6grammar.pm ; perl6 -vwk -e'print qq(ok\n)'

If this prints I<ok> at the end, then it should be so.  If not, let's
look, what is broken.

The B<perl6> compiler spits out PIR files (parrot intermediate language),
also known as IMCC files, because this is the name of the intermediate
code compiler. So, after above test you should have a file named
F<__eval__.imc> in your current working directory. Have a look into it.

It should look similar to this:

	.sub __main
		call __setup
		call _main
		end
		ret
	.sub _main
		saveall
		$P1 = new PerlArray
		$I3 = 0
		$P1[$I3] = "ok\n"
		inc $I3
		.arg	$P1
		call	_print
		restoreall
		ret
	... # more here

(Comments left out for brevity). If that's ok, we go on to:

=head2 IMCC

The intermediate code compiler reads above F<.imc> file and  - with
current default behaviour - spits out parrot assembler files.

Let's try it manually:

	../imcc/imcc -v -o __eval__.pasm __eval__.imc
	Reading __eval__.imc
	using optimization '0'
	assembly module __eval__.pasm written.
	481 lines compiled.

Now you should have a file F<__eval__.pasm>, which starts like so:

	__main:
		bsr __setup
		bsr _main
		end
		ret
	_main:
		saveall
		new P0, 10	 # .PerlArray
		set I0, 0
		set P0[I0], "ok\n"
		...

If not, B<imcc> is to blame. When it fails, you should see an error
message, telling, what went wrong.

You could try:

	../imcc/imcc -v  -r __eval__.imc
	Reading __eval__.imc, executing
	using optimization '0'
	481 lines compiled.
	Running...
	ok

So running directly is ok, but compiling to PASM is broken, if you get
above output. Not to bad, you could run perl6 programs through B<imcc>,
which is B<parrot> plus a small compiler ;-)

	perl6 --test -r

runs all tests through B<imcc>. This will probably be the default run option
for the next future.

=head2 assembling the pasm

The next step is running above parrot assembly file through the
assembler (which is again imcc running in a diffrent mode) to generate
PBC (parrot byte code).

	../imcc/imcc -o ok.pbc __eval__.pasm

This generates the binary file F<ok.pbc>, if the assembler worked.

=head2 and finally running

	../../parrot ok.pbc
	ok

=head1 Summary

These individual steps are currently run by the B<perl6> driver program.
Though there are, as already shown above, some short cuts:

	perl6 -r examples/life.p6

runs the program F<examples/life.p6> directly through B<imcc>.

	perl6 -r -Rc examples/life.p6

runs the program and writes F<examples/life.pbc> for later running by
B<parrot>.

	perl6 -k -RPd -v examples/life.p6

Above option I<-k> tells perl6 to keep intermediate files. So you can
run them with the appropriate command or you can run them with the perl6
driver. Flags after I<-R> are passed on to the running program: B<imcc>
or B<parrot>, though the former has some more options.

	perl6 ../../examples/assembly/life.pasm
	perl6 ../../examples/assembly/mops.pasm -Cv

DWIM.

=head1 Reporting bugs

If any of the above steps fail, please report the bug to
E<lt>bugs-parrot@bugs6.perl.orgE<gt> with the output of

	perl6 --version

and a description of the problem. If all tests are failing, please
provide the intermediate files for one of the tests by running e.g.

	perl6 -wk t/compiler/{testnumber}_{subtest}.p6

If particular tests fail, please provide the test summary plus
symptomatic cases of failures.

And finally, don't forget to report your OS environment including
involved components like B<perl> and C compiler.

Thanks.

=head1 AUTHOR

Leopold Tötsch E<lt>lt@toetsch.atE<gt>

$Id: debugging.pod,v 1.3 2003/08/29 17:07:12 chromatic Exp $

=cut
