Rakudo Perl -- Perl 6 on Parrot
Parrot Perl C
Pull request Compare This branch is 22299 commits behind rakudo:nom.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
build
docs
dynext
lib
src
t
tools
.gitignore
CREDITS
Configure.pl
LICENSE
README
Test.pm
perl6.pir

README

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.

Installing with your package manager

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

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

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

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 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 (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 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 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 --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 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).

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 Pugs repository 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 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.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 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-projects.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 identifier in the first output line of the git log command. 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 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 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 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.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 96:

Non-ASCII character seen before =encoding in 'Perl 6'. Assuming UTF-8