# Copyright (C) 2001-2005, The Perl Foundation.
# $Id: gettingstarted.pod 19732 2007-07-09 19:53:24Z coke $

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

There is a web interface to the subversion repository, in case you just want to
browse the source.

L<http://svn.perl.org/viewcvs/parrot/>

=item *

The easiest solution is to grab the most recent snapshot of the Parrot SVN
repository. It's a tar-gzipped download of a recent checkout of Parrot, updated
every six hours. You can find it here:

L<http://svn.perl.org/snapshots/parrot/parrot-latest.tar.gz>

=item *

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

    svn checkout https://svn.perl.org/parrot/trunk parrot

=item *

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

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

=back

The above instructions are also on the Parrot website:

L<http://www.parrotcode.org/source.html>

=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.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 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:

    % make html

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 developer file and gain an immediate overview of what
the source file is for, the algorithms it implements, etc.

NB: We need more developer 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
parrot-porters (aka perl6-internals) mailing list. There are a variety
of interfaces to the list:

=over 4

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

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

=item * Parrot NNTP Interface

L<news://nntp.perl.org/perl.perl6.internals>

L<http://nntp.x.perl.org/group/perl.perl6.internals>

=item * Parrot Archives

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

L<http://www.nntp.perl.org/group/perl.perl6.internals>

=item * Searching the Parrot Mailing List

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.

L<http://www.google.com/search?sourceid=navclient&q=site:archive%2Edevelooper%2Ecom+perl6+internals>

L<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 C<parrot-porters@perl.org> and C<perl6-language@perl.org> are
posted to C<perl6-announce@perl.org>. Alternately, you can find these summaries
here:

L<http://www.nntp.perl.org/group/perl.perl6.announce>

L<http://dev.perl.org/perl6/list-summaries/>

Or if you prefer to subscribe to the list:

L<http://lists.perl.org/showlist.cgi?name=perl6-announce>

=back

In addition, there is a mailing list which logs all commits to the Parrot SVN 
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)

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

=item * Parrot Commits NNTP Interface

L<news://nntp.perl.org/perl.cvs.parrot>

L<http://nntp.x.perl.org/group/perl.cvs.parrot>

=item * Commit List Archives

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

L<http://www.nntp.perl.org/group/perl.cvs.parrot>

=item * Searching the Parrot Commits List

After clicking the below links, just add your search terms to the Google search
box.

L<http://www.google.com/search?sourceid=navclient&q=site:archive%2Edevelooper%2Ecom+cvs+parrot>

L<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.  Visit the channel #parrot on the IRC
server L<irc.perl.org>.  Alternative IRC servers are
L<irc.rhizomatic.net> and L<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:

L<http://bugs6.perl.org/>

Or if you want to submit a patch, send an email to
C<parrotbug@parrotcode.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 C<parrot-porters@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:

L<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 C<parrotbug@parrotcode.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:

L<http://www.parrotcode.org/resources>

=over 4

=item * Parrot Wiki

Located at:

L<http://www.parrotcode.org/wiki>

=back

=head1 VERSION

=over 4

=item Revision 0.2 - 10 November 2006

Remove link to old wiki page (dead since 2004.)

Add irc.perl.org IRC server.

=item Revision 0.1 - 27 July 2002

Written to prepare for the fallout from TPC 6.

=back

=cut