The nice thing about Perl 6 implementations is that as significant portion of them is written in Perl 6. (Well, one nice thing anyway.) This means that if you're comfortable writing Perl 6 modules and classes, you should feel pretty much at home in the source.
This guide assumes so, and that you have a basic familiarity with Github,
make-- enough to commit to repositories and build a software package, anyway.
Getting StartedThis first thing is to get your own branch of Rakudo to work on. So go to the Rakudo repository and click the fork button in the upper right. Relax while Github photocopies a book. Once that's done, find an appropriate directory to
git cloneit to on your own machine.
Go ahead and cd into the new
rakudodirectory. There are a few setup things that you'll want to do. First of all, go ahead and build Rakudo, using the normal steps:
perl ./Configure.pl --gen-parrot
That will pull a copy of NQP and Parrot, and make sure that everything is working okay to begin with. Now that that's done, you'll want to add the new perl6 to your system
$PATHenvironment variable. Which, if you don't know how to do it -- well here's Google. In particular, you'll need to add the full path to the
There's a couple more things you'll want to do now. First of all:
You don't have to run the full tests now, but let it download the roast repository into your
t/specbefore hitting ^C. You will need these tests later to make sure you didn't break anything.
Next, you'll want to set up a link back to the main Rakudo repository, so you can pull changes from there. So do:
git remote add upstream git://github.com/rakudo/rakudo.git
You'll also want the module installer, Panda. Now, obviously, you shouldn't add anything to Rakudo that depends on an outside module. But Panda is the one piece of software you really don't want to break, ever. People will still want to be able to download modules even if functionality changes. We will have to go through a deprecation cycle if you intentionally change something to cause Panda to start failing its tests. So to download and install it:
git clone git://github.com/tadzik/panda.git
This will set up Panda's dependencies, and test all of those modules. The bootstrap script will tell you a path to add to your $PATH environment variable -- add it too, so that panda will run from anywhere.
Finally, you really should set up a new branch to work on, so you can switch back to a working Rakudo if you need to. Move back into the rakudo directory and run:
git checkout -b mynewbranchname
A very short overview of the source
Now that all the setup is done, let's take a quick look around. Most of what we build into Perl 6 lives in the
rakudo/srcfolder, so this is where you'll want to edit the contents.
vmdirectory contains files specific to the virtual machines Rakudo runs under. At this time of this writing, there's only one thing in there,
parrot, but very soon there will also be a
jvmdirectory. Exciting! Most of the purpose of this code is to map functions to lower-level operations, in either Parrot or Java.
Perl6directory contains the grammar and actions used to build the language, as well as the object metamodel. The contents of this folder are written in NQP, or Not Quite Perl. This section determines how the language is parsed.
coredirectory contains the files that will be built into the core setting. You'll find classes or subroutines in here for just about everything in Perl: strings, operators like
eq, filehandles, sets, and more. Individual files look similar to modules, but these are "modules" that are available to every Perl 6 program.
gendirectory contains files that are created in the compliation process. The core setting lives here, creatively named
CORE.setting. And if you look at it, it's just a concatenation of the files in
core, put together in the order specified in
rakudo/tools/build/Makefile.in. While these files can and do get overwritten in the build process, it's often a good idea to keep a copy of CORE.setting open so you can find what you're looking for faster -- and then go edit it in
Let's start hacking!
Now's the time to start changing Rakudo. Have the appropriate amount of fun! Be sure to commit functioning changes occasionally, so that you can
git bisectfor problems later. And push your edits to Github as a free backup. If you get stuck, drop by #perl6 on irc.freenode.net and ask questions.
If it's your first time, you have to fi^W^W^W^W you will probably make a lot of mistakes. I know I did on my first project, as explained in detail in a previous post. But I promise you, the learning curve is surprisingly easy, and your compiler-fu will increase to fuchsia-belt level in no time. (What? We're not just giving black belts away... and Camelia likes fuchsias.)
Testing and Specs
When you think you're finished with your code, the first thing you should do is merge in the upstream rakudo, and rebuild:
git fetch upstream
git merge upstream/nom
The spectests will make sure that you didn't accidentally break the codebase. You should pass, or at least not fail worse than the current roast data.
You should add your own tests into the roast repository about now. You do have unit tests, right? Writing tests is "optional", just like brushing your teeth -- you don't have to do it, but if you never do it you're in for a lot of pain later. Here's a fine and elegantly crafted hyperlink to S24 (Testing) for reference.
When editing a file that already exists in roast, you may need to fudge the tests for Niecza and Pugs. This tells us "we know the test failed or fails to parse, nothing has changed". Just add lines like the following above broken tests:
#?pugs 1 skip 'reason'
#?niecza 1 skip 'reason'
The "1" is actually the number of tests you want to skip, but really, look at the README in roast for more details.
If you want to add a whole new test file, you'll need to add it into
rakudo/t/spectest.data. If your code fixes broken tests, then you'll want to *unfudge* by removing the
#?rakudo skiplines above the relevant tests.
You should also test that Panda is still working. Since you'll have to rebuild panda after recompling Rakudo anyway, just check the rebootstrap for test failures:
Commiting to Rakudo
The easiest way to get your code merged is to push it back to Github, and then send a pull request into Rakudo. If you're really committed to committing, consider sending in a Contributor License Agreement to The Perl Foundation. This makes you eligible for a commit bit to push directly to the Rakudo repo.
If there's a problem, someone will get back to you pretty fast on the Github issues page. Hopefully, these problems will be easy to fix, and a standard
git commit; git pushwill add it to the ticket. If there aren't any problems, someone will just merge it in a couple days.
Huzzah! \o/ A Rakudo Hacker is you!