docs/gettingstarted.pod

   1 # Copyright (C) 2001-2009, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/gettingstarted.pod - Parrot Developer FAQ
   7
   8 =head1 DEVELOPER FAQ
   9
  10 =head2 I'm interested in helping out. What should I do?
  11
  12 You're already on the right track. This FAQ should help you find everything you
  13 need to become an active member of the Parrot community. Just look through the
  14 questions below and read the ones that apply to you.
  15
  16 More current information is also available at
  17 L<https://trac.parrot.org/parrot/wiki/NewParrotDeveloperGuide>.
  18
  19 =head2 Where can I get Parrot?
  20
  21 =over 4
  22
  23 =item *
  24
  25 There is a web interface to the subversion repository, in case you just want to
  26 browse the source.
  27
  28 L<https://trac.parrot.org/parrot/browser>
  29
  30 =item *
  31
  32 The easiest solution is to grab the latest monthly development release. You can
  33 find it here:
  34
  35 L<http://www.parrot.org/release/current>
  36
  37 =item *
  38
  39 An even better option is to use SVN, which gets you the very latest copy of the
  40 Parrot distribution. The procedure for this is:
  41
  42     svn checkout https://svn.parrot.org/parrot/trunk parrot
  43
  44 =item *
  45
  46 If you're using git-svn, you should check out just the latest version. First:
  47
  48 C<< git svn clone -s -r HEAD https://svn.parrot.org/parrot >>
  49
  50 =back
  51
  52 The above instructions are also on the Parrot website:
  53
  54 L<http://www.parrot.org/download>
  55
  56 =head2 Now that I've got Parrot, what do I do?
  57
  58 Now that you've downloaded Parrot, you probably want to try it out. All you
  59 need is Perl 5.8.0 or later, a C compiler (any ANSI C compliant compiler
  60 should do - if you find one that doesn't work, please report it to us), and
  61 some reasonable form of C<make>. To do this, follow these three easy steps.
  62
  63 =over 4
  64
  65 =item 1
  66
  67 C<cd> to your parrot directory and run C<Configure.pl> to create the makefile
  68 for your platform.
  69
  70 =item 2
  71
  72 Run C<make> to compile everything and build parrot.
  73
  74 =item 3
  75
  76 Run C<make test> to run the test suite and verify that everything works on
  77 your system.
  78
  79 =back
  80
  81
  82
  83 =head2 Where's the Parrot documentation?
  84
  85 Well, Parrot documentation is a great place to contribute, should you be
  86 looking for something to do. Figure out which parts were confusing, and either
  87 help us fix them, or let us know where we should fix them. Luckily, all of the
  88 current Parrot documentation is included along with the Parrot distribution, in
  89 the /docs/ directory.
  90
  91 There is also some experimental auto-generated HTML documentation available by
  92 running the following command in the Parrot distribution's root directory:
  93
  94     % make html
  95
  96 To view the HTML documentation start with the page F<docs/html/index.html>.
  97
  98 There are a few categories of documentation, each with different intents. It'll
  99 probably help to be aware of them before you go digging in. I highly suggest
 100 you check out F</docs/pdds/pdd07_codingstd.pod> for guidelines on how
 101 documentation is supposed to be laid out. For now, here's the executive
 102 summary:
 103
 104 =over 4
 105
 106 =item * PDDs
 107
 108 Parrot Design Documents (PDDs) document the basic design of the Parrot
 109 interpreter, with each PDD focusing on a particular topic, such as the design
 110 of the garbage collector (PDD 09) or the object system (PDD 15). They can be
 111 found in the F</docs/pdds> directory.
 112
 113 NB: Some important areas are still missing PDDs; we're working to rectify that.
 114
 115 =item * Developer files
 116
 117 These are files which correspond to a specific source file, and can be found in
 118 F</docs/dev/>. A developer file contains documentation on all the
 119 implementation decisions associated with the source file. (Note that this is in
 120 contrast to PDDs, which describe design decisions). This is the place for
 121 mini-essays on how to avoid overflows in unsigned arithmetic, or on the pros
 122 and cons of differing hash algorithms, and why the current one was chosen, and
 123 how it works.
 124
 125 If you are coming to a particular source file for the first time, you should
 126 be able to read the developer file and gain an immediate overview of what
 127 the source file is for, the algorithms it implements, etc.
 128
 129 NB: We need more developer files too. Patches welcome!
 130
 131 =item * Source file documentation
 132
 133 Each source file includes comments embedded in the document. Usually this means
 134 function-level documentation that describes the purpose and intent of a
 135 function, along with any other important information. For larger functions, it
 136 will include additional documentation that explains the meaning of code, as
 137 opposed to a verbatim translation of code.
 138
 139 =back
 140
 141 =head2 Where can I find the main developer mailing list?
 142
 143 Most of the Parrot-related development discussion occurs on the
 144 parrot-dev (previously known as parrot-porters and perl6-internals) mailing
 145 list. There are a variety of interfaces to the list:
 146
 147 =over 4
 148
 149 =item * Developer Mailing List Interface (subscribing, unsubscribing, etc)
 150
 151 L<http://lists.parrot.org/mailman/listinfo/parrot-dev>
 152
 153 =item * Parrot NNTP Interface
 154
 155 L<nntp://news.gmane.org/gmane.comp.compilers.parrot.devel>
 156
 157 =item * Parrot Archives, RSS
 158
 159 L<http://groups.google.com/group/parrot-dev> provides archives, search,
 160 and RSS feeds.
 161
 162 L<http://news.gmane.org/gmane.comp.compilers.parrot.devel>
 163
 164 L<http://lists.parrot.org/pipermail/parrot-dev/>
 165
 166 =back
 167
 168 In addition, there is a mailing list which logs all commits to the Parrot SVN
 169 repository. If you're interested in Parrot development, you might find it very
 170 helpful to subscribe and keep up on changes that people are making.
 171
 172 =over 4
 173
 174 =item * Mailing List Interface (subscribing, unsubscribing, etc)
 175
 176 L<http://lists.parrot.org/mailman/listinfo/parrot-commits>
 177
 178 =item * Parrot Commits NNTP Interface
 179
 180 L<...>
 181
 182 L<...>
 183
 184 =item * Commit List Archives, RSS
 185
 186 L<...>
 187
 188 L<http://lists.parrot.org/pipermail/parrot-commits/>
 189
 190 =back
 191
 192
 193 =head2 What other ways can I get in contact with the Parrot developers?
 194
 195 The mailing list is the main resource for Parrot development. However, there
 196 is an IRC channel which you may find useful if your problem is better solved
 197 with real-time discussion.  Visit the channel #parrot on the IRC
 198 server L<irc.parrot.org>.  Alternative IRC servers are
 199 L<irc.rhizomatic.net> and L<irc.pobox.com>.
 200
 201
 202
 203 =head2 I've developed a patch. What should I do with it?
 204
 205 See F<docs/submissions.pod> for details.
 206
 207 =head2 I've found a bug, what now?
 208
 209 See F<docs/submissions.pod> for details.
 210
 211 =head2 What other useful resources are there for developers?
 212
 213 A number of other useful resources that can be found via on the Parrot
 214 wiki, located at L<http://trac.parrot.org/parrot/wiki>.