Getting Started

Building Parrot

The first step before you start playing with Parrot is to get a copy of the source code and compile it. You can download the latest monthly release from http://www.parrot.org/release/current.

To build Parrot you'll need a C compiler and a make utility. Generally, you'll use gcc and make, but many different versions of these tools are supported on different operation systems. Perl is also needed for parts of the configuration and build process. The following command-line instructions will build the core virtual machine and compiler toolkit, and run the standard test suite.

  $ perl Configure.pl
  $ make
  $ make test

Once you've compiled Parrot, you can run your first small script. Create a test file in the main parrot directory called fjord.pasm. .pasm files are written in primative Parrot Assembly Language (PASM) which is a low-level programming interface to Parrot.

  print "He's pining for the fjords.\n"
  end

Now run this file with:

  $ ./parrot fjord.pasm

which will print:

  He's pining for the fjords.

Next, try out one of Parrot's high-level languages. Create a test file called hello.nqp:

  say "Hello, World!"

Then run it as:

  $ ./nqp hello.nqp

This will print, of course, the phrase "Hello, World". NQP stands for Not Quite Perl, it's a mini language that's very similar to the Perl 6 programming language. NQP is part of the Parrot Compiler Tools (PCT) and is an integral part of building compilers for Parrot. We will talk more about NQP and the rest of the PCT tools, and how to use these for building compilers for Parrot in chapter 9.

In the next few chapters we will discuss more aspects of Parrot programming using low-level PASM language, and a higher-level interface language called PIR. Chapters 3 and 4 will talk about PIR, which is the primary way to program Parrot directly. Chapter 5 will talk about PASM, and the low-level programming interface.

Build Requirements

There are a number of requirements for building Parrot from source, and a number of optional libraries and components that can be used to extend its capabilities. None of these requirements or optional components are necessary unless you are building Parrot from the source code.

In addition to these build requirements listed above, there are a number of Perl libraries needed to enable all tests and testing facilities, and to generate all the necessary documentation.

To get the Perl packages for Parrot, you can use the commands:

  sudo cpan Test::Base Test::Pod Test::Pod::Coverage Pod::Spell
  sudo cpan File::HomeDir File::Which Readonly Regexp::Parser
  sudo cpan Perl::Critic Perl::Critic::Bangs Test::Perl::Critic

Use the source

The second step to participating in Parrot development is to get a copy of the source code. If you just want to try it out--experiment with a few features and see how it feels--the best option is to download the most recent point release for your system. Point releases are usually packaged up for easy download and install for various platforms, including Windows, Debian, and Redhat. Point releases are also available from CPAN. The sure way to get the most recent release is at http://search.cpan.org/dist/parrot/ (or search for "parrot" in "Distributions"). If you want something a little more cutting edge than the packaged release, a new snapshot of the subversion repository is created every eight hours. The most recent snapshot is always available at http://cvs.perl.org/snapshots/parrot/parrot-latest.tar.gz.

If you plan to get involved in development, you'll want to check out the source from the subversion repository directly. Anyone can get anonymous access to read the files and download a working copy to explore and test. For commit access, volunteers need a https://trac.parrot.org username, and need to be approved by a Metacommitter. To download the most recent version from SVN, type this command into your terminal This is for Linux users, on Mac or Windows systems, follow the instructions from your SVN client:

  svn co https://svn.parrot.org/parrot/trunk parrot

There's also a web interface for viewing files in the repository at http://svn.parrot.org/parrot/.

The repository is large and complex, so it's worth taking a little bit of time to explore. The code changes constantly, but most files and functions have informative descriptions to help keep track of things.

The most important top-level directory is docs/. The content isn't always up to date, but it is a good place to start. parrot.pod provides a quick overview of what's in each documentation file. If you're a capable writer and know a thing or two about how Parrot works, the documentation is a great place to start contributing. This book that you're reading right now was created in docs/book/ by ordinary contributors. Most other documentation files found here are parsed and converted to HTML for display at http://www.parrot.org.

There are a number of existing language implementations for Parrot: Perl 6, Python ("Pynie"), Ruby ("Cardinal"), PHP ("Pipp"), Lisp, Lua, Tcl ("partcl"), WMLScript, Forth, Scheme, Befunge, BASIC, and many others. These language compilers are in various stages of partial completion. The page https://trac.parrot.org/parrot/wiki/Languages provides meta information on these languages and where to find them. If you have a language you're particularly interested to see implemented on Parrot, you can see how far along the effort is, or you can start the work to implement it yourself. We'll talk more about creating new compilers in Chapter 10: High-Level Languages, if you're interested.

The lib/ directory contains Perl 5 classes currently used in developing, building, and testing Parrot. The src/pmc/ directory contains the C source code for Parrot classes (PMCs, which you'll read more about in CHP-11Chapter 11).

Most Parrot development happens in src/ for the C source code, and include/parrot/ for the C development header files.

Libraries for use by programs running on Parrot are found in runtime/.

The examples/ directory contains some example Parrot PIR and Assembly code, as well as benchmarks. More discussions about these topics will be found in CHP-3 Chapter 3, CHP-5 Chapter 5, and CHP-7 Chapter 7 respectively.