HTTP/1.1 -1 Read error in cache disk data: SuccessContent-Type: text/plain; charset="utf-8" Last-Modified: Sat, 22 Jan 2022 04:25:55 GMT Content-length: 6566 Connection: Close Proxy-Connection: Close X-Cache: HIT from web1.osuosl.org Server: ProxyTrack 0.5 (HTTrack 3.49.2) == Newcomers Welcome! == We're going to do our best to document the experiences of newcommers to Perl, Parrot and Open Source software development. Hopefully this will evolve into a road map for those who wish to contribute but are having trouble getting started. == Before you start == Before you download and compile Parrot, you may want to check you system to make sure you have the following packages installed. * [http://perl.org Perl] * perl-doc * [http://subversion.tigris.org/ subversion] * [http://freshmeat.net/projects/diffstat/ diffstat] == Getting Parrot == If your going to become part of the development team, you'll need to check out a local copy of the source code. You can visit the [http://www.parrotcode.org/source.html download] page on the main Parrot web site for full details. You'll need to make sure you have the following already installed on your machine. Assuming you've got Perl, perl-doc and Subversion installed you'll be doing something like this. {{{ ~$ svn co https://svn.perl.org/parrot/trunk parrot ~$ cd parrot ~$ perl Configure.pl ~$ make ~$ make test ~$ make html }}} One make target to avoid right now is install. Running make install is not currently recommended. == Running Parrot == Make compiled a binary in the parrot build directory. {{{ ~$ ./parrot --version }}} You may want to create a symbolic link to this binary, somewhere in your path, so that you can run parrot from anywhere. {{{ ~$ ln -s ~/parrot/parrot /usr/bin/parrot ~$ parrot --version }}} == Learning Parrot == You've downloaded, configured, compiled, tested and created the html documentation for Parrot. Now it's time to start reading. Parrots source documentation is stored in [http://en.wikipedia.org/wiki/Plain_Old_Documentation POD] format. If you ran make html you can the view the documentation as html. The file docs/html/index.html is the place to start. An alternative and more flexible method for viewing the documentation is to use [http://search.cpan.org/dist/Pod-Perldoc/lib/perldoc.pod perl-doc] to view the actual pod files. Perldoc will allow you to view the pod files formated as man pages. It cannot be stressed enough how important it is to read the documentation for this project. The bare minimum reading needed to get you off the ground is: * docs/info.pod * docs/gettingstarted.pod After you read those, you'll want to run through all of the tutorials in examples/tutorial. Next on your reading list should be the PDDs (Parrot Design Documents). You will learn much by reading these, so don't skimp. == Contributing == By now you've read the introductory documentation and reviewed the example/tutorial files. Now you have to decide what area of the project you'd like to contribute to. === Test Suite === Original Parrot tests where written in Perl. Those Perl tests can be ported to PIR test. This is a good place to earn your feathers and learn more PIR at the same time. [http://www.perlfoundation.org/parrot/index.cgi?convert_existing_tests_to_parrot Converting existing tests to Parrot] covers what you'll need to know about the format of a PIR test. If your not familiar with the test suite functions you'll want to review parrot/runtime/library/Test/More.pir. The functions section gives a description of the different testing functions like: plan, diag, ok, nok, is, is_deeply, like, isa_ok, skip, isnt and todo. This is a good time to point out that POD can and usually is embedded in PIR files. So if your in the root build directory you can run the following to view the module documentation: {{{ ~$ perldoc parrot/runtime/library/Test/More.pir }}} You already now that make test runs the test suite, but when working on individual tests you'll want to run only the test your concerned with. You can do this using Perls prove for a Perl test or either prove or Parrot itself for PIR tests. {{{ ~$ prove t/oo/names.t t/oo/names....ok All tests successful. Files=1, Tests=2, 0 wallclock secs ( 0.05 cusr + 0.01 csys = 0.06 CPU) or ~$ parrot t/oo/names.t 1..2 ok 1 - HLL obj w/ name different than parrot obj created ok 2 - HLL obj w/ same name as parrot obj not created }}} = Test Conversion = Here is the original Perl test. [http://www.perlfoundation.org/parrot/index.cgi/names.t.orig?action=attachments_download;page_name=starting_at_the_bottom;id=20081113142645-0-29575 names.t.orig] Here is the same test after being converted to PIR: [http://www.perlfoundation.org/parrot/index.cgi/names.t?action=attachments_download;page_name=starting_at_the_bottom;id=20081113142713-0-29174 names.t] == Submitting your work == Once again there is a POD covering this topic. Read doc/submissions.pod for specific details on how to submit your work. In general you'll need to create a patch and then email that patch to perlbug. {{{ ~$ svn status ~$ svn diff > names_test_rewrite.patch ~$ diffstat names_test_rewrite.patch names.t | 63 +++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 30 deletions(-) }}} [http://www.perlfoundation.org/parrot/index.cgi/names_test_rewrite.patch?action=attachments_download;page_name=starting_at_the_bottom;id=20081113142750-0-29058 names_test_rewrite.patch] Then you'll need to send an email, with the patch as an attachment, to Perlbug. It should look something like this. {{{ from Your Name to parrotbug at parrotcode.org subject [PATCH] rewrite of names.t to PIR This is a rewrite of t/oo/names.t from a perl test to a PIR test names.t | 63 +++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 33 insertions(+), 30 deletions(-) -- }}} Parrotbug will autoreply to your submission with an RT Ticket Id. Here's an example of a typical response. {{{ Greetings, This message has been automatically generated in response to the creation of a parrotbug regarding: "[PATCH] rewrite of names.t to PIR" There is no need to reply to this message right now. Your ticket has been assigned an ID of [perl #60512]. Please include the string: [perl #60512] In the subject line of all future correspondence about this issue. To do so, you may reply to this message. Thank you, parrotbug http://rt.perl.org/rt3/Ticket/Display.html?id=60512 }}} It's that simple. >make fulltest</tt>. </p> <p> Did no harm to <tt>make test</tt> on Linux/i386, as per <a class="ext-link" href="htt