# Copyright (C) 2008, 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<http://www.parrotcode.org/glossary.html>),
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 on
irc.parrot.org#parrot.

=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<http://www.parrotcode.org/docs/pdd/pdd19_pir.html>.

=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
