docs/gettingstarted.pod - Parrot Developer FAQ
You're already on the right track. This FAQ should help you find everything you need to become an active member of the Parrot community. Just look through the questions below and read the ones that apply to you.
If you're just interested in browsing the CVS repository without downloading anything, a few interfaces exist.
http://cvs.perl.org/cvsweb/parrot/
http://cvs.perl.org/viewcvs/parrot/
The easiest solution is to grab the most recent snapshot of the Parrot CVS repository. It's a tar-gzipped download of a recent checkout of Parrot, updated every six hours. You can find it here:
http://cvs.perl.org/snapshots/parrot/parrot-latest.tar.gz
Even better is the option to use CVS, which gets you the very latest copy of the Parrot distribution. The procedure for this is:
cvs -d :pserver:anonymous@cvs.perl.org:/cvs/public login
[press enter at the password prompt]
cvs -d :pserver:anonymous@cvs.perl.org:/cvs/public co parrot
Or, if you're one of those rsync folks, you can access the repository with:
rsync -av --delete cvs.perl.org::parrot-HEAD parrot
For the Parrot CVS website with the above instructions, check out:
http://cvs.perl.org/
Now that you've downloaded Parrot, you probably want to try it out. All you need is Perl 5.005_03 or later, a C compiler (any ANSI C compliant compiler should do - if you find one that doesn't work, please report it to us), and some reasonable form of make. To do this, follow these three easy steps.
make
cd to your parrot directory and run Configure.pl to create the makefile for your platform.
cd
Configure.pl
Run make to compile everything and build parrot.
Run make test to run the test suite and verify that everything works on your system.
make test
Well, Parrot documentation is a great place to contribute, should you be looking for something to do. Figure out which parts were confusing, and either help us fix them, or let us know where we should fix them. Luckily, all of the current Parrot documentation is included along with the Parrot distribution, in the /docs/ directory.
There is also some experimental auto-generated HTML documentation available by running the following command in the Parrot distribution's root directory:
% perl tools/docs/write_docs.pl -s
To view the HTML documentation start with the page docs/html/index.html.
There are a few categories of documentation, each with different intents. It'll probably help to be aware of them before you go digging in. I highly suggest you check out /docs/pdds/pdd07_codingstd.pod for guidelines on how documentation is supposed to be laid out. For now, here's the executive summary:
PDDs
Parrot Design Documents (PDDs) document the basic design of the Parrot interpreter, with each PDD focusing on a particular topic, such as the design of the garbage collector (PDD 09) or the object system (PDD 15). They can be found in the /docs/pdds directory.
NB: Some important areas are still missing PDDs; we're working to rectify that.
Developer files
These are files which correspond to a specific source file, and can be found in /docs/dev/. A developer file contains documentation on all the implementation decisions associated with the source file. (Note that this is in contrast to PDDs, which describe design decisions). This is the place for mini-essays on how to avoid overflows in unsigned arithmetic, or on the pros and cons of differing hash algorithms, and why the current one was chosen, and how it works.
If you are coming to a particular source file for the first time, you should be able to read the .dev file and gain an immediate overview of what the source file is for, the algorithms it implements, etc.
NB: We need more .dev files too. Patches welcome!
Source file documentation
Each source file includes comments embedded in the document. Usually this means function-level documentation that describes the purpose and intent of a function, along with any other important information. For larger functions, it will include additional documentation that explains the meaning of code, as opposed to a verbatim translation of code.
Most of the Parrot-related development discussion occurs on the perl6-internals mailing list. There are a variety of interfaces to the list:
Mailing List Interface (subscribing, unsubscribing, etc)
http://lists.perl.org/showlist.cgi?name=perl6-internals
NNTP Interface
news://nntp.perl.org/perl.perl6.internals
http://nntp.x.perl.org/group/perl.perl6.internals
Archives
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&group=perl.perl6.internals
http://www.nntp.perl.org/group/perl.perl6.internals
Searching
There are no directly searchable interfaces to the mailing lists. However, Google works quite well. After clicking the below links, just add your search terms to the Google search box.
http://www.google.com/search?sourceid=navclient&q=site:archive%2Edevelooper%2Ecom+perl6+internals
Summaries
If you find the traffic too much to keep up with, weekly summaries of the discussion on perl6-internals@perl.org and perl6-language@perl.org are posted to perl6-announce@perl.org. Alternately, you can find these summaries here:
http://www.nntp.perl.org/group/perl.perl6.announce
http://dev.perl.org/perl6/list-summaries/
Or if you prefer to subscribe to the list:
http://lists.perl.org/showlist.cgi?name=perl6-announce
In addition, there is a mailing list which logs all commits to the Parrot CVS repository. If you're interested in Parrot development, you might find it very helpful to subscribe and keep up on changes that people are making.
http://lists.perl.org/showlist.cgi?name=cvs-parrot
news://nntp.perl.org/perl.cvs.parrot
http://nntp.x.perl.org/group/perl.cvs.parrot
http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&group=perl.cvs.parrot
http://www.nntp.perl.org/group/perl.cvs.parrot
After clicking the below links, just add your search terms to the Google search box.
http://www.google.com/search?sourceid=navclient&q=site:archive%2Edevelooper%2Ecom+cvs+parrot
The mailing list is the main resource for Parrot development. However, there is an IRC channel which you may find useful if your problem is better solved with real-time discussion. To find this channel, visit the channel #parrot in the following IRC servers (either one will do):
irc://irc.rhizomatic.net/ or irc://irc.pobox.com/
There's a lot of traffic that goes through the mailing list, and it's quite possible that if you send patches directly to the mailing list, they will get lost in the mailboxes of those with commit access.
As such, a better solution would be to submit your patch to RT, the request tracker system that maintains bugs and patches for the Parrot project. To visit RT, go here:
http://bugs6.perl.org/
Or if you want to submit a patch, send an email to bugs-parrot@bugs6.perl.org with the moniker [PATCH] (including the brackets) at the start of the subject so that it can be appropriately tagged in the RT system. Please note that you do not have to CC perl6-internals@perl.org when reporting a bug. The RT system will correctly handle that on its own.
A listing of the pending patches can be found here:
http://www.parrotcode.org/openpatches
Well, if you know enough about the bug that you can fix the problem, please do so. Then you can create a patch and submit it to the list, with a better chance of your bug getting attention. If you're not able to solve it on your own, we're still interested in seeing what the problem is, and hopefully helping to resolve it. To report a bug, email bugs-parrot@bugs6.perl.org with a brief description of your bug in the subject. For more information about the bug management system, see the previous question.
There are several other useful resources that can be found via:
http://www.parrotcode.org/resources
Experimental Parrot Wiki
Located at:
http://www.vendian.org/parrot/wiki/
A collection of various other pieces of useful Parrot information and documentation that have yet to make it into the CVS repository. Includes a comprehensive guide to getting started with Parrot development (called, unsurprisingly, 'Getting Started with Parrot Development').
Tinderbox
The tinderbox consists of a number of different computers running various OS and platform configurations, downloading the latest Parrot distribution every few hours and running the test suite to verify that it works on that given combination of software and hardware.
To view the results of the tinderbox system, check out:
http://tinderbox.perl.org/tinderbox/bdshowbuild.cgi?tree=parrot
Tinderbox Failure Summary
A brief summary of the current status of the various tinderbox machines. Useful for finding out which tests are failing (if any).
Test Coverage Results
The Parrot test suite is intended to test all aspects of Parrot's code. You can see how successful we are at this goal by checkout the test coverage. It gives line, branch, and call coverage percentages on a per-file or per-function breakdown. Find it here:
http://www.hitchhiker.org/parrot_coverage/
Bonsai
Bonsai is a cvs tree control tool to monitor the status of cvs trees. Whenever a checkin occurs, bonsai adds that person to the "hook," a list of those responsible for the current state of the tree (this should be cleared whenever we know that things are working for sure). Users can then run queries to find out who has changed what files and access their checkin comments in addition to generating diffs.
Query
http://tinderbox.perl.org/bonsai/cvsqueryform.cgi?cvsroot=/home/tinder/perlcvs&module=parrot
Browse
http://tinderbox.perl.org/bonsai/rview.cgi?cvsroot=/home/tinder/perlcvs&dir=parrot&module=parrot
Written to prepare for the fallout from TPC 6.
To install Ruby, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ruby
CPAN shell
perl -MCPAN -e shell install Ruby
For more information on module installation, please visit the detailed CPAN module installation guide.