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.

    This directory contains only the Rakudo Perl 6 compiler itself; it 
    does not contain any of the modules, documentation, or other items
    that would normally come with a full Perl 6 distribution.  If you're
    after more than just the bare compiler, please download the latest
    Rakudo Star package from http://github.com/rakudo/star/downloads .

  Build requirements (Installing from source)
    For building Rakudo you need at least a C compiler, a "make" utility,
    and Perl 5.8 or newer. To automatically obtain and build Parrot you
    may also need a a git client, which is also needed for fetching the
    test suite.

    In order to fully support Unicode, you'll also want to have the ICU
    library installed (<http://site.icu-project.org/>). Rakudo can run
    without ICU, but some Unicode-related features do 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 git-core

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

  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 <http://github.com/rakudo/rakudo/downloads>. Then unpack the
    tarball or zip.

    If you already have cloned Rakudo from github, you can get (pull) the
    most recent version from github like this:

        $ cd rakudo
        $ git pull

    Once you have an up-to-date 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. Note that if you have multiple (Perl 5) "perl"s in
    your path, you may need to use a fully qualified path to the appropriate
    executable (or update your PATH environment variable).

    Programs can then be run from the build directory using a command like:

        $ ./perl6 hello.pl

    Important: To run Rakudo from outside the build directory, you must run

        $ make install

    This will install the "perl6" (or "perl6.exe" binary on windows) into
    the "parrot_install/bin" directory locally, no additional root
    privileges necessary.

    The "--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
    "--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 "--parrot-config=/path/to/parrot_config" instead of
    "--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 "make install" target or by
    installing prebuilt "parrot-devel" and/or "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 "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 "make" above
    can only be reliably run from the root of Rakudo's build directory.
    After "make install" is performed, the installed 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.

    See the manual page ("docs/running.pod") for more about command-line
    options.

   Build/install problems
    Occasionally, there may be problems when building/installing Rakudo.
    Make sure you have a backup of any custom changes you have done to the
    source tree before performing the following steps:

    Try to remove the "parrot_install" subdirectory:

        $ cd rakudo
        $ rm -r parrot_install
        $ git pull
        $ perl Configure.pl --gen-parrot
        $ make

    Or, in case you are really stuck, start with a fresh source tree:

        $ rm -r rakudo
        $ git clone git://github.com/rakudo/rakudo.git

  Running the test suite
    Entering "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 "make spectest" will import the official Perl 6 test suite from
    the "roast" repository <http://github.com/perl6/roast/> 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 "make spectest_smolder" instead. You need the
    Perl 5 module TAP::Harness::Archive and an active internet connection
    for that. The smoke results are collected at
    <http://smolder.parrot.org/app/projects/smoke_reports/5>

    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 roast 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 Test::Harness (3.16 works for sure).

  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 "perl6-users@perl.org"
    mailing list. This list is primarily for the people who want to *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 "perl6-compiler@perl.org". Discussion about Parrot
    itself generally takes place on "parrot-dev@lists.parrot.org".

    The Rakudo and Parrot development teams tend to hang out on IRC a fair
    bit, either on "irc.freenode.net/#perl6" or "irc.perl.org/#parrot".

    Rakudo's official web site is <http://rakudo.org/>, where you can find
    useful information for developers and users alike. There's also a Parrot
    blog at <http://parrotblog.org/>, most Perl 6 related news is assembled
    at <http://planetsix.perl.org/>. Links to many other resources can be
    found on <http://perl6.org/>.

  Reporting bugs
    Bug reports should be sent to "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 information in the output from "perl6 --version" (or in
    the first line of "git log", if Rakudo fails to build). There's no need
    to cc: the perl6-compiler mailing list, as the RT system will handle
    this on its own.

  Submitting patches
    If you have a patch that fixes a bug or adds a new feature, please
    submit it to "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 "git" command is greatly preferred. In general this means that in
    the "rakudo" directory you make your changes, and then type

        git commit -m 'Your commit message' changed/filename.pm
        git format-patch HEAD^

    This will generate a file called "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 "git-am
    -s" command; it preserves meta information like author).

    Other ways to create and submit patches are discussed here:
    <http://wiki.github.com/rakudo/rakudo/steps-to-create-a-patch>.

  How the compiler works
    See docs/compiler_overview.pod.

AUTHOR
    Patrick Michaud "pmichaud@pobox.com" is the primary author and
    maintainer for Rakudo Perl 6 on Parrot. See CREDITS for further authors.