# Copyright: 2001-2004 The Perl Foundation.  All Rights Reserved.
# $Id: gettingstarted.pod 5471 2004-02-28 09:18:02Z mikescott $

=head1 NAME

docs/gettingstarted.pod - Parrot Developer FAQ

=head1 DEVELOPER FAQ

=head2 I'm interested in helping out. What should I do?

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.

=head2 Where can I get Parrot?

=over 4

=item *

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/

=item *

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

=item *

Even better is the option to use CVS, which gets you the very latest copy of 
the Parrot distribution. The procedure for this is:

C<cvs -d :pserver:anonymous@cvs.perl.org:/cvs/public login>

C<[press enter at the password prompt]>

C<cvs -d :pserver:anonymous@cvs.perl.org:/cvs/public co parrot>

=item *

Or, if you're one of those rsync folks, you can access the repository with:

C<rsync -av --delete cvs.perl.org::parrot-HEAD parrot>

=back

For the Parrot CVS website with the above instructions, check out:

http://cvs.perl.org/

=head2 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.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 C<make>. To do this, follow these three easy steps.

=over 4

=item 1

C<cd> to your parrot directory and run C<Configure.pl> to create the makefile 
for your platform.

=item 2

Run C<make> to compile everything and build parrot.

=item 3

Run C<make test> to run the test suite and verify that everything works on 
your system.

=back

=head2 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 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 F<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 F</docs/pdds/pdd07_codingstd.pod> for guidelines on
how documentation is supposed to be laid out. For now, here's the executive 
summary:

=over 4

=item * 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 F</docs/pdds> directory.

NB: Some important areas are still missing PDDs; we're working to rectify 
that.

=item * Developer files

These are files which correspond to a specific source file, and can be found 
in F</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 F<.dev> file and gain an immediate overview of what the 
source file is for, the algorithms it implements, etc.

NB: We need more F<.dev> files too. Patches welcome!

=item * 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.

=back



=head2 Where can I find the main developer mailing list?

Most of the Parrot-related development discussion occurs on the 
perl6-internals mailing list. There are a variety of interfaces to the list:

=over 4

=item * Mailing List Interface (subscribing, unsubscribing, etc)

http://lists.perl.org/showlist.cgi?name=perl6-internals

=item * NNTP Interface

news://nntp.perl.org/perl.perl6.internals

http://nntp.x.perl.org/group/perl.perl6.internals

=item * 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

=item * 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

http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&group=perl.perl6.internals

=item * 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

=back

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.

=over 4

=item * Mailing List Interface (subscribing, unsubscribing, etc)

http://lists.perl.org/showlist.cgi?name=cvs-parrot

=item * NNTP Interface

news://nntp.perl.org/perl.cvs.parrot

http://nntp.x.perl.org/group/perl.cvs.parrot

=item * Archives

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

=item * Searching

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

http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&oe=UTF-8&group=perl.cvs.parrot

=back



=head2 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 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/



=head2 I've developed a patch. What should I do with it?

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 B<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



=head2 I've found a bug, what now?

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.



=head2 What other useful resources are there for developers?

There are several other useful resources that can be found via:

http://www.parrotcode.org/resources

=over 4

=item * 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').

=item * 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

=item * 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).

=item * 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/

=item * 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.

=over 4

=item * Query

http://tinderbox.perl.org/bonsai/cvsqueryform.cgi?cvsroot=/home/tinder/perlcvs&module=parrot

=item * Browse

http://tinderbox.perl.org/bonsai/rview.cgi?cvsroot=/home/tinder/perlcvs&dir=parrot&module=parrot


=back

=back

=head1 VERSION

=over 4

=item Revision 0.1 - 27 July 2002

Written to prepare for the fallout from TPC 6.

=back

=cut

