Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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