# Copyright (C) 2008-2011 Parrot Foundation. =head1 NAME Getting Started with the Parrot Compiler Tools =head1 DESCRIPTION This document can be considered your Number One entry point for starting to use the Parrot Compiler Tools (PCT). As there's a whole lot of acronyms flying around (see Parrot's glossary at L<https://github.com/parrot/parrot/blob/master/docs/glossary.pod>), this document will get you up and running within 10 minutes (that excludes building Parrot). Once you begin, it's a matter of getting your hands dirty and get experienced using the tools. Feel free to ask questions in the #parrot channel on irc.parrot.org . =head1 GETTING STARTED Getting started using the PCT is easy. The steps are: =over 4 =item * download and build Parrot =item * generate a language stub =item * customize your language =back The acronyms you will encounter, are: =over 4 =item * PASM Stands for Parrot Assembly language, and is a textual form of the bytecodes that Parrot is running. PASM's syntax is very primitive, which is a pain to write, which is why Parrot has something called PIR. =item * PIR Stands for Parrot Intermediate Representation. This is a fancy layer of syntactic sugar on top of PASM. If you program Parrot natively, you write in PIR. Other documents discuss PIR syntax, for instance L<https://github.com/parrot/parrot/blob/master/docs/pdds/pdd19_pir.pod> =item * PGE Stands for Parrot Grammar Engine, and is the regular expression engine of Parrot. It is written in PIR. Regular expressions in Perl 6 are more powerful than Perl 5's regexes, as you can write language grammars more easily. These C<regular expressions> are written in Perl 6 C<rules>. See Perl 6 synopsis 5 (S05, at L<http://dev.perl.org/perl6/doc/design/syn/S05.html>) for the syntax of Perl 6 rules. A grammar is processed by PGE to create a language parser. The grammar can contain special tokens that look like C<{*}> and invoke a subroutine by the same name as the current rule. These invoked subroutines are commonly called C<actions>. =item * NQP Stands for Not Quite Perl, and is a I<subset> of Perl 6. Yeah, that's right, you can already program in Perl 6 today (well, if you're happy with a simpler version of the language). NQP is implemented in PIR. The reason for building NQP was that it makes writing the parse actions (see C<PGE>) a whole lot easier. Although PIR is a neat language, it's still quite primitive. =item * PAST PAST stands for Parrot Abstract Syntax Tree, and is a library of classes that define the nodes for abstract syntax trees. Typical node types are C<PAST::Val> representing literal values (such as 42, "Hello World", etc.) and C<PAST::Var> which represents variables (for instance when writing C<my $var;> in Perl 6). The parse actions discussed earlier can construct these PAST nodes, so that at the end of the parse, you have a complete abstract syntax tree representing the program you compiled. =item * POST Stands for Parrot Opcode Syntax Tree, and is another library of classes that define the nodes for so-called opcode syntax trees. For this beginner's guide you can forget about it, but at some point you'll see the term C<POST>. Just forget about it for now. =back Now we discussed the most important acronyms, it's time to get up and running. =head2 Download and Build Parrot Get Parrot from L<http://www.parrot.org/download> and build it. If you're lucky and you have a fast computer, it should be done within 5 minutes. It's always useful to run the test suite by typing: $ make test =head2 Generate a Language Stub There's a special script for newcomers: F<tools/dev/mk_language_shell.pl>. Invoke it from Parrot's root directory: $ perl tools/dev/mk_language_shell I<language> I<location> For instance, if you want to create a language called C<Foo> in the directory C<languages/foo>, type: $ perl tools/dev/mk_language_shell Foo languages/foo This will create a complete language that compiles out of the box. You first need to run the C<Configure.PL> Perl script to generate the C<Makefile>. Then you can run C<make> and C<make test>. $ cd languages/foo $ perl Configure.pl $ make $ make test Yes, that's right, there's even a test file already created for you. This makes setting up the tests for your language very easy! The generated directories and files have the following structure: foo/ /Configure.pl # configuration script /config/makefiles/root.in # input for the Makefile generator # as long as you don't add source files, # there's no need to update this file. /src/ /parser/ /actions.pm # the language's grammar rules; a file /grammar.pm # containing the parse actions; /grammar-oper.pg # file containing a default operator table. /builtins/ /say.pir # a file containing a built-in function /pmc/ /foo.pmc # file defining vtable functions /ops/ /foo.ops # file defining opcodes # TODO: add more "standard library" routines here /t/ /00-sanity.t # a test file /harness # file to set up the test framework # more tests can be added here /foo.pir # file containing the main routine /README # an almost empty readme file /STATUS # an almost empty status file /MAINTAINER # a file for you to add your details to When you want to run a script through your language's compiler, (assuming you're in your language's directory, in this case F<languages/foo>) type: $ ../../parrot foo.pbc file.foo You can give an command line option to your compiler which specifies what kind of output you want. This is the C<target> option: $ ../../parrot foo.pbc --target=pir file.foo this will print the generated PIR instructions to stdout. Other options for the C<target> option are C<parse>, C<past>, and C<post>. =head2 Customize Your Language You probably have some language syntax in mind to implement. Note that the grammar defined in the file C<languages/foo/src/parser/grammar.pg> and the parse actions in the file C<languages/foo/src/parser/actions.pm> are closely related (especially note the names of the action methods). It's very important to update the methods accordingly if you change the grammar rules. =head1 COMMON ERROR MESSAGES This section describes some common error messages and how to resolve them. This is a work in progress, so you might not find your issue/solution here. If you have anything new to add, please send a patch (or an email) to C<parrotbug@parrotcode.org>. =over 4 =item * no result object This is the case when you try to retrieve the result object from a subrule, but the subrule's action didn't set a result object using the C<make> command. Check whether there's an action invocation token C<{*}> in the subrule and whether that subrule's action has a C<make> command. =back =head1 WHERE TO GO FROM HERE? =head2 Documents The following documents might be useful to learn more: =over 4 =item * L<languages/squaak/doc/> This directory contains the Parrot Compiler Toolkit Tutorial, describing the implementation of a simple yet non-trivial language. =item * L<docs/past_building_blocks.pod> =item * L<docs/pdds/pdd26_past.pod> =item * L<docs/pdds/pdd19_pir.pod> =item * F<http://dev.perl.org/perl6/doc/design/syn/S05.html> =back =head2 Other Languages You can also have a look at some existing languages that are being developed using the PCT, all located in the C<languages> subdirectory of Parrot. These are: perl6 (commonly referred to as C<Rakudo>), lua (see the L<lua/pct> directory), ecmascript (a standardized C<JavaScript>), punie (Perl 1 on Parrot), pynie (Python on Parrot), and cardinal (Ruby on Parrot). =head2 IRC Everyday, a bunch of Parrot enthusiasts can be found on #parrot on irc.parrot.org. You're welcome to ask questions. =head1 SUGGESTIONS If you have suggestions, improvements, tips or complaints about this document, please send an email to C<parrot-dev@lists.parrot.org>. =cut