Parrot Developer FAQ

soh-cah-toa edited this page Sep 23, 2011 · 2 revisions

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.

More current information is also available at the New Parrot Developer Guide.

"Where can I get Parrot?"

  • If you just want to browse the source code, you can use the web interface to the GitHub repository.

  • The easiest solution is to grab the latest development release which is available at http://www.parrot.org/release/current

If you're ready to start hacking, an even better option is to use git to clone a local copy of the very latest version of the Parrot distribution. You can do so by running:

git clone git://github.com/parrot/parrot.git parrot

Git clients are available for most modern operating systems. To see if your platform is supported, visit http://git-scm.com/.

The above instructions are also on the Parrot website (http://www.parrot.org/download).

"Now that I've got Parrot, what do I do?"

Now that you've downloaded Parrot, you probably want to try it out. All you need is Perl 5.8.0 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.

  1. cd to the Parrot root directory and run perl Configure.pl to create the Makefile for your platform.
  2. Run make to compile everything and build Parrot.
  3. Run make test to run the test suite and verify that everything works on your system.

"Where's the Parrot documentation?"

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 they need to be improved. 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 root directory:

$ make html

To view the HTML documentation, start with the docs/html/index.html page.

There are several different categories of documentation, each with different purposes. It'll probably help to be aware of them before you go digging in. It is suggested that you read docs/pdds/pdd07_codingstd.pod for guidelines on how documentation is supposed to be laid out. Here is a general summary:

  • PDD's

    • Parrot Design Documents (PDD's) provide an overview of 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.
  • 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; this is in contrast to PDD's 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 reading a particular source file for the first time, you should be able to read the developer file and gain an understanding of what the source file is for, the algorithms it implements, etc.

  • Source file documentation

    • Each source file includes comments embedded in the file. This usually 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 the code as opposed to a verbatim translation of code.

"Where can I find the main developer mailing list?"

Most of the Parrot-related development discussion occurs on the parrot-dev (previously known as parrot-porters and perl6-internals) mailing list. There are a variety of interfaces to the list:

Additionally, there is another mailing list - parrot-commits which logs all commits to the GitHub 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.

"What other ways can I get in contact with the Parrot developers?"

The mailing list is the main resource for Parrot development. However, there is also an IRC channel which you may find useful if your problem is better solved with real-time discussion. Visit the #parrot channel on irc.parrot.org. Alternative IRC servers are irc.rhizomatic.net and irc.pobox.com.

"I've created a patch. What should I do with it?"

See Parrot Submission Instructions for details.

"I've found a bug, what now?"

See Parrot Submission Instructions for details.

"What other useful resources are there for developers?"

A number of other useful resources that can be found via on the Parrot wiki.