rakudo / rakudo

=head1 Rakudo Perl 6

This is Rakudo Perl, a Perl 6 compiler for the Parrot virtual machine.

Rakudo Perl is Copyright (C) 2008-2010, The Perl Foundation.
Rakudo Perl is distributed under the terms of the Artistic License 2.0.
For more details, see the full text of the license in the file LICENSE.

=head2 Installing with your package manager

Rakudo is currently available for Arch Linux users in the AUR at
(L<http://aur.archlinux.org/packages.php?ID=29068>).

FreeBSD users may find the Rakudo port at
L<http://rakudoport.sourceforge.net/> useful.

Windows users can download binary builds from
L<http://sourceforge.net/projects/parrotwin32/files/> and need the
I<parrotwin32 setup> and the matching version of
I<parrot-rakudo addon>.

=head2 Build requirements (Installing from source)

For building Rakudo you need at least a C compiler, a C<make> utility,
and Perl 5.8 or newer.  To automatically obtain and build Parrot
or the spectest suite you may also need a subversion (svn) client.

In order to fully support Unicode, you'll also want to have the
ICU library installed (L<http://site.icu-project.org/>).
Rakudo can run without ICU, but some Unicode-related features
may not work properly.

As an example, on Debian GNU/Linux or Ubuntu Linux the necessary
components for building Rakudo can be installed via the command

    aptitude install build-essential libicu-dev subversion

(Perl is installed by default already). To enable parallel testing you
also need the CPAN module L<Test::Harness> in version 3.16 or newer;
you can control the number of parallel jobs with the C<TEST_JOBS>
environment variable.

=head2 Building and invoking Rakudo

Because Rakudo is under rapid development, we generally recommend
downloading Rakudo directly from github and building from there:

    $ git clone git://github.com/rakudo/rakudo.git

If you don't have git installed, you can get a tarball or zip of Rakudo
from github by visiting http://github.com/rakudo/rakudo/tree/master
and clicking "Download".  Then unpack the tarball or zip.

Once you have a copy of Rakudo, build it as follows:

    $ cd rakudo
    $ perl Configure.pl --gen-parrot
    $ make

This will create a "perl6" or "perl6.exe" executable in the
current (rakudo) directory.  Programs can then be run from
the build directory using a command like:

    $ ./perl6 hello.pl

The C<--gen-parrot> above option tells Configure.pl to automatically
download and build the most appropriate version of Parrot into
a local "parrot/" subdirectory, install that Parrot into
the "parrot_install/" subdirectory, and use that for building
Rakudo.  It's okay to use the C<--gen-parrot> option on later
invocations of Configure.pl; the configure system will re-build
Parrot only if a newer version is needed for whatever version
of Rakudo you're working with.

You can use C<--parrot-config=/path/to/parrot_config> instead
of C<--gen-parrot> to use an already installed Parrot for building
Rakudo.  This installed Parrot must include its development
environment; typically this is done via Parrot's C<make install>
target or by installing prebuilt C<parrot-devel> and/or C<libparrot-dev>
packages.  The version of the already installed Parrot must satisfy a
minimum specified by the Rakudo being built -- Configure.pl will
verify this for you.  Released versions of Rakudo always build
against the latest release of Parrot; checkouts of the HEAD revision
from github often require a version of Parrot that is newer than
the most recent Parrot monthly release.

Once built, Rakudo's C<make install> target will install Rakudo
and its libraries into the Parrot installation that was used to
create it.  Until this step is performed, the "perl6" executable
created by C<make> above can only be reliably run from the root of
Rakudo's build directory.  After C<make install> is performed
the executable can be run from any directory (as long as the
Parrot installation that was used to create it remains intact).

If the Rakudo compiler is invoked without an explicit script to
run, 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 C<make test> will run a small test suite that comes
bundled with Rakudo.  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 C<make spectest> will import the official Perl 6 test suite
from the Pugs repository L<http://svn.pugscode.org/pugs/t/spec/>
and run all of these tests that are currently known to pass.

If you want to automatically submit the results of your spectest run
to a central server, use C<make spectest_smolder> instead. You need
the Perl 5 module L<TAP::Harness::Archive> and an active internet
connection for that. The smoke results are collected at
L<http://smolder.plusthree.com/app/public_projects/details/18>.

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.

You can also use "make" to run an individual test from the command line:

    $ 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

If you want to run the tests in parallel, you need to install a
fairly recent version of the Perl 5 module L<Test::Harness> (3.16
works for sure).

=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 Rakudo and Parrot development teams tend to hang out on IRC a fair
bit, either on C<irc.freenode.net/#perl6> or C<irc.perl.org/#parrot>.

Rakudo's official web site is L<http://rakudo.org/>, where you can
find useful information for developers and users alike. There's also
a Parrot blog at L<http://parrotblog.org/>, most Perl 6 related news is
assembled at L<http://planetsix.perl.org/>. Links to many other
resources can be found on L<http://perl6-projects.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 include either the release name/date or the git commit
identifier. You find that identifier in the first output line of
the C<git log> command.  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<http://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 C<pmichaud@pobox.com> is the primary author and
maintainer for Rakudo Perl 6 on Parrot.

=cut

## vim: expandtab sw=4 ft=pod tw=70: