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,
git
, and make
-- enough to commit to repositories and build a software package, anyway.Getting Started
This 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 togit clone
it to on your own machine.Go ahead and cd into the new
rakudo
directory. 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
make
make install
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
$PATH
environment 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 rakudo/install/bin
directory.There's a couple more things you'll want to do now. First of all:
make spectest
You don't have to run the full tests now, but let it download the roast repository into your
t/spec
before 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
cd panda
perl6 bootstrap.pl
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/src
folder, so this is where you'll want to edit the contents.- The
vm
directory 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 ajvm
directory. Exciting! Most of the purpose of this code is to map functions to lower-level operations, in either Parrot or Java. - The
Perl6
directory 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. - The
core
directory 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 likeeq
, filehandles, sets, and more. Individual files look similar to modules, but these are "modules" that are available to every Perl 6 program. - The
gen
directory contains files that are created in the compliation process. The core setting lives here, creatively namedCORE.setting
. And if you look at it, it's just a concatenation of the files incore
, put together in the order specified inrakudo/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 incore
.
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 bisect
for 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
perl Configure.pl
make
make spectest
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 skip
lines 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:
perl6 panda/rebootstrap.pl
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 push
will 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!
great share
ReplyDeleteI as of late ran over your website and have been perusing along. I thought I would leave my first remark. I don't realize what to say with the exception of that I have delighted in perusing. Decent blog. I will continue going to this web journal regularly. HQ DOFOLLOW
ReplyDelete