1# Copyright (C) 2008-2011, Parrot Foundation.
2
3=head1 NAME
4
5Getting Started with the Parrot Compiler Tools
6
7=head1 DESCRIPTION
8
9This document can be considered your Number One entry point for starting to
10use the Parrot Compiler Tools (PCT). There will be a whole lot of acronyms
11flying around.  Consult L<< Parrot's glossary|http://docs.parrot.org/parrot/latest/html/docs/glossary.html >> about
12them.  This document will get you up and running within 10 minutes (that
13excludes building Parrot). Once you begin, it's a matter of getting your hands
14dirty and get experienced using the tools. Feel free to ask questions in the
15#parrot channel on irc.parrot.org .
16
17=head1 GETTING STARTED
18
19Getting started using the PCT is easy.  The steps are:
20
21=over 4
22
23=item * download and build Parrot
24
25=item * generate a language stub
26
27=item * customize your language
28
29=back
30
31The acronyms you will encounter, are:
32
33=over 4
34
35=item * PASM
36
37Stands for Parrot Assembly language, and is a textual form of the bytecodes
38that Parrot is running. PASM's syntax is very primitive, which is a pain to
39write, which is why Parrot has something called PIR.
40
41=item * PIR
42
43Stands for Parrot Intermediate Representation. This is a fancy layer of
44syntactic sugar on top of PASM. If you program Parrot natively, you
45write in PIR. Other documents discuss PIR syntax, for instance
46L<https://github.com/parrot/parrot/blob/master/docs/pdds/pdd19_pir.pod>
47
48=item * PGE
49
50Stands for Parrot Grammar Engine, and is the regular expression engine of
51Parrot. It is written in PIR. Regular expressions in Perl 6 are more powerful
52than Perl 5's regexes, as you can write language grammars more easily. These
53C<regular expressions> are written in Perl 6 C<rules>.  See Perl 6 synopsis 5
54(S05, at L<http://dev.perl.org/perl6/doc/design/syn/S05.html>) for the syntax
55of Perl 6 rules.  A grammar is processed by PGE to create a language parser.
56The grammar can contain special tokens that look like C<{*}> and invoke a
57subroutine by the same name as the current rule. These invoked subroutines are
58commonly called C<actions>.
59
60=item * NQP
61
62Stands for Not Quite Perl, and is a I<subset> of Perl 6. Yeah, that's right,
63you can already program in Perl 6 today (well, if you're happy with a simpler
64version of the language). NQP is implemented in PIR. The reason for building
65NQP was that it makes writing the parse actions (see C<PGE>) a whole lot
66easier. Although PIR is a neat language, it's still quite primitive.
67
68=item * PAST
69
70PAST stands for Parrot Abstract Syntax Tree, and is a library of classes that
71define the nodes for abstract syntax trees. Typical node types are C<PAST::Val>
72representing literal values (such as 42, "Hello World", etc.) and C<PAST::Var>
73which represents variables (for instance when writing C<my $var;> in Perl 6).
74The parse actions discussed earlier can construct these PAST nodes, so that at
75the end of the parse, you have a complete abstract syntax tree representing the
76program you compiled.
77
78=item * POST
79
80Stands for Parrot Opcode Syntax Tree, and is another library of classes that
81define the nodes for so-called opcode syntax trees. For this beginner's guide
82you can forget about it, but at some point you'll see the term C<POST>.  Just
83forget about it for now.
84
85=back
86
87Now we discussed the most important acronyms, it's time to get up and running.
88
89=head2 Download and Build Parrot
90
91Get Parrot from L<http://www.parrot.org/download> and build it. If
92you're lucky and you have a fast computer, it should be done within 5 minutes.
93It's always useful to run the test suite by typing:
94
95 $ make test
96
97=head2 Generate a Language Stub
98
99There's a special script for newcomers: F<tools/dev/mk_language_shell.pl>.
100Invoke it from Parrot's root directory:
101
102 $ perl tools/dev/mk_language_shell I<language> I<location>
103
104For instance, if you want to create a language called C<Foo> in the directory
105C<languages/foo>, type:
106
107 $ perl tools/dev/mk_language_shell Foo languages/foo
108
109This will create a complete language that compiles out of the box.  You first
110need to run the C<Configure.PL> Perl script to generate the C<Makefile>.  Then
111you can run C<make> and C<make test>.
112
113 $ cd languages/foo
114 $ perl Configure.pl
115 $ make
116 $ make test
117
118Yes, that's right, there's even a test file already created for you. This makes
119setting up the tests for your language very easy!
120
121The generated directories and files have the following structure:
122
123 foo/
124    /Configure.pl                # configuration script
125    /config/makefiles/root.in    # input for the Makefile generator
126                                 # as long as you don't add source files,
127                                 # there's no need to update this file.
128    /src/
129        /parser/
130               /actions.pm       # the language's grammar rules; a file
131               /grammar.pm       # containing the parse actions;
132               /grammar-oper.pg  # file containing a default operator table.
133
134        /builtins/
135                 /say.pir        # a file containing a built-in function
136
137        /pmc/
138                 /foo.pmc        # file defining vtable functions
139
140        /ops/
141                 /foo.ops        # file defining opcodes
142                                 # TODO: add more "standard library" routines here
143    /t/
144      /00-sanity.t               # a test file
145      /harness                   # file to set up the test framework
146                                 # more tests can be added here
147
148    /foo.pir                     # file containing the main routine
149    /README                      # an almost empty readme file
150    /STATUS                      # an almost empty status file
151    /MAINTAINER                  # a file for you to add your details to
152
153
154When you want to run a script through your language's compiler, (assuming
155you're in your language's directory, in this case F<languages/foo>) type:
156
157 $ ../../parrot foo.pbc file.foo
158
159You can give an command line option to your compiler which specifies what kind
160of output you want. This is the C<target> option:
161
162 $ ../../parrot foo.pbc --target=pir file.foo
163
164this will print the generated PIR instructions to stdout. Other options for the
165C<target> option are C<parse>, C<past>, and C<post>.
166
167=head2 Customize Your Language
168
169You probably have some language syntax in mind to implement.  Note that the
170grammar defined in the file C<languages/foo/src/parser/grammar.pg> and the
171parse actions in the file C<languages/foo/src/parser/actions.pm> are closely
172related (especially note the names of the action methods). It's very important
173to update the methods accordingly if you change the grammar rules.
174
175=head1 COMMON ERROR MESSAGES
176
177This section describes some common error messages and how to resolve them. This
178is a work in progress, so you might not find your issue/solution here. If you
179have anything new to add, please send a patch (or an email) to
180C<parrotbug@parrotcode.org>.
181
182=over 4
183
184=item * no result object
185
186This is the case when you try to retrieve the result object from a subrule, but
187the subrule's action didn't set a result object using the C<make> command.
188Check whether there's an action invocation token C<{*}> in the subrule and
189whether that subrule's action has a C<make> command.
190
191=back
192
193=head1 WHERE TO GO FROM HERE?
194
195=head2 Documents
196
197The following documents might be useful to learn more:
198
199=over 4
200
201=item * L<languages/squaak/doc/>
202
203This directory contains the Parrot Compiler Toolkit Tutorial, describing the
204implementation of a simple yet non-trivial language.
205
206=item * L<docs/past_building_blocks.pod>
207
208=item * L<docs/pdds/pdd26_past.pod>
209
210=item * L<docs/pdds/pdd19_pir.pod>
211
212=item * F<http://dev.perl.org/perl6/doc/design/syn/S05.html>
213
214=back
215
216=head2 Other Languages
217
218You can also have a look at some existing languages that are being developed
219using the PCT, all located in the C<languages> subdirectory of Parrot. These
220are: perl6 (commonly referred to as C<Rakudo>), lua (see the L<lua/pct>
221directory), ecmascript (a standardized C<JavaScript>), punie (Perl 1 on
222Parrot), pynie (Python on Parrot), and cardinal (Ruby on Parrot).
223
224=head2 IRC
225
226Everyday, a bunch of Parrot enthusiasts can be found on #parrot on
227irc.parrot.org. You're welcome to ask questions.
228
229=head1 SUGGESTIONS
230
231If you have suggestions, improvements, tips or complaints about this document,
232please send an email to C<parrot-dev@lists.parrot.org>.
233
234=cut
235