=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 2 steps that might be the culprit:

=over 4

=item P6C -- the perl6 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 was 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 Parrot

Parrot runs above F<.imc> file directly with the passed options.

Let's try it manually:

	../../parrot -G __eval__.imc

This turns off DOD/GC, which might be helpful to verify, that some
DOD/GC bug is still lurking around.

=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 examples/life.p6

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

	perl6 -Rj -v examples/life.p6

runs the program with the JIT core.

	perl6 -RPd -v -k 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 B<parrot>.

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

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 5342 2004-02-22 12:06:19Z leo $

=cut
