=head1 Rakudo Perl 6
This is the Perl 6 compiler for Parrot, called "Rakudo Perl 6",
or "Rakudo" for short.  It's still fairly basic, but it is rapidly expanding.
See L<docs/STATUS> for a list of what has been implemented thus far.
=head2 Building and invoking Rakudo
If you build Rakudo for the first time, you need to get and build a
copy of parrot:
    $ svn checkout https://svn.parrot.org/parrot/trunk parrot
    $ cd parrot
    $ perl Configure.pl
    $ make
Then go to the C<languages> subdirectory and get, configure and build 
Rakudo there:
    $ git clone git://github.com/rakudo/rakudo.git
    cd rakudo
    perl Configure.pl
    make
This will create the compiler as a file called "perl6.pbc".  The ".pbc"
stands for "Parrot bytecode", and represents an executable Parrot
module.
To update your Parrot and Rakudo working copies, type C<svn up> in
Parrot's directory and build it with C<make>, and C<git pull; make>
Rakudo's directory.
To run a Perl 6 program with Rakudo, issue a command like
    $ parrot perl6.pbc hello.pl
If you want to create a binary executable of the compiler
that can be invoked as "perl6" from the command line, then
try "make perl6".  This will create a "perl6" (or "perl6.exe")
binary that can be directly used from the command line:
    $ ./perl6 hello.pl
This binary executable feature is still somewhat experimental,
and may not work on all platforms.  Also, the binary has hardcoded
paths to the Parrot build tree (especially the dynamic libraries
and modules), so removing the build tree will cause the binary
to stop working.
If the Rakudo compiler is invoked without an explicit script to
run -- i.e., as "parrot perl6.pbc" or just "perl6" -- it enters a
small interactive mode that allows Perl 6 statements to be
executed from the command line.  Each line entered is treated
as a separate compilation unit, however (which means that subroutines
are preserved after they are defined, but variables are not).
=head2 Running the test suite
Entering "make test" will run the test suite that comes bundled
with Rakudo on Parrot.  This is a simple suite of tests, designed
to make sure that the Rakudo compiler is basically working and that
it's capable of running a simple test harness.
Running "make spectest" will import relevant portions
of the "official Perl 6 test suite" from the Pugs repository
L<https://svn.pugscode.org/pugs/t/spec/> and run all of these tests that
are currently known to pass.
At present we do not have any plans to directly store the
official test suite as part of the Rakudo/Parrot repository,
but will continue to fetch it from the Pugs repository.
While in the C<languages/rakudo> directory, you can an individual test from the
command line with:
    $ make t/spec/S29-str/ucfirst.t
    t/spec/S29-str/ucfirst.rakudo .. 
    1..4
    ok 1 - simple
    ok 2 - empty string
    ok 3 - # SKIP unicode
    ok 4 - # SKIP unicode
    # FUDGED!
    ok
    All tests successful.
    Files=1, Tests=4,  1 wallclock secs ( 0.02 usr  0.00 sys +  0.57 cusr  0.06 csys =  0.65 CPU)
    Result: PASS
=head2 Where to get help or answers to questions
There are several mailing lists, IRC channels, and wikis available
with help for Perl 6 and Rakudo on Parrot.  Figuring out the right
one to use is often the biggest battle.  Here are some rough
guidelines:
If you have a question about Perl 6 syntax or the right way to
approach a problem using Perl 6, you probably want the
C<perl6-users@perl.org> mailing list.  This list is primarily
for the people who want to I<use> Perl 6 to write programs, as
opposed to those who are implementing or developing the Perl 6
language itself.
Questions about the Rakudo compiler for Parrot and the Parrot
compiler tools can go to C<perl6-compiler@perl.org>.  Discussion
about Parrot itself generally takes place on
C<parrot-dev@lists.parrot.org>.
The Parrot and Rakudo development team tend to hang out on IRC a fair
bit, either on C<irc.perl.org/#parrot> or C<irc.freenode.net/#perl6>.
There are also Perl 6 and Parrot wikis, found at
    L<https://www.perlfoundation.org/perl6/index.cgi>
    L<https://www.perlfoundation.org/parrot/index.cgi>
There is also a Rakudo related blog at L<https://rakudo.org/>, and
a Parrot blog at L<https://parrotblog.org/>. Most Perl 6 related news is
assembled at L<https://planetsix.perl.org/>.
=head2 Reporting bugs
Bug reports should be sent to C<rakudobug@perl.org> with the moniker
[BUG] (including the brackets) at the start of the subject so that
it gets appropriately tagged in the RT system (https://rt.perl.org/rt3/).
Please include or attach any sample source code that exhibits the
bug, and if appropriate identify the svn revision number of the code
that you're working from.  There's no need to cc: the perl6-compiler
mailing list, as the RT system will handle this on its own.
=head2 Submitting patches
If you have a patch that fixes a bug or adds a new feature, please
submit it to C<rakudobug@perl.org> with the moniker [PATCH]
(including the brackets) at the start of the subject line.  We'll
generally accept patches in any form if we can get them to work,
but unified diff from the C<git> command is greatly preferred.  In
general this means that in the C<languages/rakudo/> directory you make your
changes, and then type
    
    git commit -m 'Your commit message'
    git-format-patch HEAD^
This will generate a file called C<001-your-commit-message.patch>, or more of
them if you made multiple commits; please attach these to your email.
(Note to the maintainers: you can apply these patches with the
C<git-am> command; it preserves meta information like author).
Other ways to create and submit patches are discussed here:
L<https://wiki.github.com/rakudo/rakudo/steps-to-create-a-patch>.
=head2 How the compiler works
See F<docs/compiler_overview.pod>.
=head1 AUTHOR
Patrick Michaud (pmichaud@pobox.com) is the primary author and
maintainer for Rakudo Perl 6 on Parrot.
=cut
## vim: expandtab sw=4 ft=pod tw=70: