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