docs/pct/gettingstarted.pod

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