<commit_before>=pod

=head1 Project Development

Z<CHP-2>

The Parrot project is specially organized to be light-weight and
efficient. The project is governed like a meritocracy; people who
make valuable contributions are offered more responsibility. Communication
is relaxed and informal, often intermittent through email and on IRC. As
Dan is so fond of saying, "This is far too important to take seriously."
The Parrot developers act a bit like a special forces unit where the
objective is pursued because the whole team knows the task at hand, not
because of any tight control from above.

=head2 Development Cycles

Z<CHP-2-SECT-2.1>

X<development cycles;Parrot>
The Parrot development cycle centers on regular "point releases." A point
release corresponds to a version change, such as 0.4.x to 0.5.x. These
releases typically happen monthly, which is good because nobody has
to guess when the next one will be. The architect and release managers
decide whether the release is a "major" or minor one, depending on the
changes that have been made and the features that have been added in the
previous month. Usually one or two solid new features trigger a major
point release. The Parrot team has specified a general roadmap of major
point releases, and the expected features and changes that will trigger
each one.

Development proceeds at a steady pace with bugs reported, patches
submitted, patches applied, and all sorts of other regular development
tasks performed. The pace isn't so much a result of careful planning as
it is the law of averages; on any given day someone, somewhere, is
working on Parrot. In periods of high activity there are often many more
people working on Parrot N<Or related tools, or high-level language
compilers, etc.> then just one. Activity tends to spike when a release
is approaching as last minute bugs, especially bugs in the build system
or bugs that cause segmentation faults, are found and fixed by the team.
After the release, there is an influx of new bug reports and other
feedback as the casual users and testers get their hands on the newest
version. These regular swells of activity are one of the major reasons
why Parrot has monthly releases.

=head2 Getting Involved

Z<CHP-2-SECT-2.2>

X<p2 (Parrot mailing list)>
X<Parrot;getting involved>
The first step to getting involved in the Parrot project, whether you
want to hack code, write documentation, or help in other ways, is to
join the Parrot-porters (p2) mailing list. The topics on p2 tend to
revolve around practical matters: bug reports, patches, notifications
of changes committed to the subversion repository, and questions on
coding style. Occasionally there are discussions about how to implement
particular features, although such discussions are often better-suited
for other communications media, such as IRC.

The Parrot developers, along with other volunteers and well-wishers
tend to congregate on IRC to have more in-depth discussions. They
maintain a chatroom C<#parrot> on the U<irc://irc.perl.org> server.
To get real-time answers to questions, or just to see how things are
progressing, the chatroom is the place to be.

=head3 Use the source

Z<CHP-2-SECT-2.2.1>

X<Parrot;source code>
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 options 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
U<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 U<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
U<http://auth.perl.org> username, and need to be approved by a
Metacommiter. To download the most recent version from SVN, type this
command into your terminal N<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
U<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 F<docs/>.  The content isn't
always up to date, but it is a good place to start. F<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 F<docs/book/> by ordinary
contributors. Most other documentation files found here are parsed and
converted to HTML for display at U<http://www.parrot.org>.

The F<languages/> directory contains the code that implements various
language compilers N<This isn't entirely true. As of the 1.0 release
of Parrot, all HLLs are supposed to reside elsewhere, not in the
Parrot repository. If the languages disappear from there, we'll
probably be nice enough to leave a note telling you where it went>:
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 L<https://trac.parrot.org/parrot/wiki/Languages>
provides meta information on
the included languages and on the many language projects that are
being developed and maintained outside the Parrot repository. 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 F<lib/> directory contains Perl 5 classes currently used in
developing, building, and testing Parrot. The F<src/pmc/> directory
contains the C source code for Parrot classes (PMCs, which you'll read
more about in A<CHP-11>Chapter 11).

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

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

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

=head1 Building Parrot

Z<CHP-2-SECT-2.2.2>

X<Parrot;source code>
The first step before you start playing with Parrot's PASM and PIR
code is to get a copy of the source code and compile it. PASM is
the Parrot assembly language and is introduced in A<CHP-5>Chapter 5.
PIR, an intermediate-level language that is used most often in compiler
development, is discussed in A<CHP-3>Chapter 3.

The basic steps involved in building Parrot from the source code from
the command line are: N<Not all operating systems have F<make>. Check
the documentation for instructions for systems that aren't Unix-based.>

  $ perl Configure.pl
  $ make
  $ make test

X<PASM (Parrot assembly language);compiling>
Once you've compiled Parrot, create a small test file in the main
F<parrot> directory.  We'll call it F<fjord.pasm>.

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

X<.pasm files>
I<.pasm> is the standard extension for Parrot assembly language source
files. Now you can run this file with:

  $ ./parrot fjord.pasm

And watch the result of the program execution. Instead of executing
the program immediately, you could also compile it to bytecode:

  $ ./parrot --output fjord.pbc fjord.pasm

You specify the name of the output bytecode file with the C<--output>
(or C<-o>) switch.  I<.pbc> is the standard extension for Parrot
bytecode. To execute the compiled bytecode, run it through the
F<parrot> interpreter:

  $ ./parrot fjord.pbc

This is, of course, a simple and contrived example. In the next few
chapters we will discuss more aspects of Parrot programming using
both PASM and PIR, and we will discuss some of the more advanced
features of Parrot that make it an interesting and attractive
programming platform.

=head3 Patch submission

Z<CHP-2-SECT-2.2.3>

X<Parrot;patch submission>
Parrot development proceeds through a continuous stream of patches.
Patches are the currency of exchange in the project--the unit of
work. Patches can fix bugs, add features, modify capabilities,<commit_msg>[Book] Add some notes about some of our development requirements. Thanks to an email from fperrad++ for the information<commit_after>=pod

=head1 Project Development

Z<CHP-2>

The Parrot project is specially organized to be light-weight and
efficient. The project is governed like a meritocracy; people who
make valuable contributions are offered more responsibility. Communication
is relaxed and informal, often intermittent through email and on IRC. As
Dan is so fond of saying, "This is far too important to take seriously."
The Parrot developers act a bit like a special forces unit where the
objective is pursued because the whole team knows the task at hand, not
because of any tight control from above.

=head2 Development Cycles

Z<CHP-2-SECT-2.1>

X<development cycles;Parrot>
The Parrot development cycle centers on regular "point releases." A point
release corresponds to a version change, such as 0.4.x to 0.5.x. These
releases typically happen monthly, which is good because nobody has
to guess when the next one will be. The architect and release managers
decide whether the release is a "major" or minor one, depending on the
changes that have been made and the features that have been added in the
previous month. Usually one or two solid new features trigger a major
point release. The Parrot team has specified a general roadmap of major
point releases, and the expected features and changes that will trigger
each one.

Development proceeds at a steady pace with bugs reported, patches
submitted, patches applied, and all sorts of other regular development
tasks performed. The pace isn't so much a result of careful planning as
it is the law of averages; on any given day someone, somewhere, is
working on Parrot. In periods of high activity there are often many more
people working on Parrot N<Or related tools, or high-level language
compilers, etc.> then just one. Activity tends to spike when a release
is approaching as last minute bugs, especially bugs in the build system
or bugs that cause segmentation faults, are found and fixed by the team.
After the release, there is an influx of new bug reports and other
feedback as the casual users and testers get their hands on the newest
version. These regular swells of activity are one of the major reasons
why Parrot has monthly releases.

=head2 Getting Involved

Z<CHP-2-SECT-2.2>

X<p2 (Parrot mailing list)>
X<Parrot;getting involved>
The first step to getting involved in the Parrot project, whether you
want to hack code, write documentation, or help in other ways, is to
join the Parrot-porters (p2) mailing list. The topics on p2 tend to
revolve around practical matters: bug reports, patches, notifications
of changes committed to the subversion repository, and questions on
coding style. Occasionally there are discussions about how to implement
particular features, although such discussions are often better-suited
for other communications media, such as IRC.

The Parrot developers, along with other volunteers and well-wishers
tend to congregate on IRC to have more in-depth discussions. They
maintain a chatroom C<#parrot> on the U<irc://irc.perl.org> server.
To get real-time answers to questions, or just to see how things are
progressing, the chatroom is the place to be.

=head3 Use the source

Z<CHP-2-SECT-2.2.1>

X<Parrot;source code>
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 options 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
U<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 U<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
U<http://auth.perl.org> username, and need to be approved by a
Metacommiter. To download the most recent version from SVN, type this
command into your terminal N<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
U<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 F<docs/>.  The content isn't
always up to date, but it is a good place to start. F<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 F<docs/book/> by ordinary
contributors. Most other documentation files found here are parsed and
converted to HTML for display at U<http://www.parrot.org>.

The F<languages/> directory contains the code that implements various
language compilers N<This isn't entirely true. As of the 1.0 release
of Parrot, all HLLs are supposed to reside elsewhere, not in the
Parrot repository. If the languages disappear from there, we'll
probably be nice enough to leave a note telling you where it went>:
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 L<https://trac.parrot.org/parrot/wiki/Languages>
provides meta information on
the included languages and on the many language projects that are
being developed and maintained outside the Parrot repository. 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 F<lib/> directory contains Perl 5 classes currently used in
developing, building, and testing Parrot. The F<src/pmc/> directory
contains the C source code for Parrot classes (PMCs, which you'll read
more about in A<CHP-11>Chapter 11).

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

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

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

=head1 Building Parrot

Z<CHP-2-SECT-2.2.2>

X<Parrot;source code>
The first step before you start playing with Parrot's PASM and PIR
code is to get a copy of the source code and compile it. PASM is
the Parrot assembly language and is introduced in A<CHP-5>Chapter 5.
PIR, an intermediate-level language that is used most often in compiler
development, is discussed in A<CHP-3>Chapter 3.

The basic steps involved in building Parrot from the source code from
the command line are: N<Not all operating systems have F<make>. Check
the documentation for instructions for systems that aren't Unix-based.>

  $ perl Configure.pl
  $ make
  $ make test

X<PASM (Parrot assembly language);compiling>
Once you've compiled Parrot, create a small test file in the main
F<parrot> directory.  We'll call it F<fjord.pasm>.

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

X<.pasm files>
I<.pasm> is the standard extension for Parrot assembly language source
files. Now you can run this file with:

  $ ./parrot fjord.pasm

And watch the result of the program execution. Instead of executing
the program immediately, you could also compile it to bytecode:

  $ ./parrot --output fjord.pbc fjord.pasm

You specify the name of the output bytecode file with the C<--output>
(or C<-o>) switch.  I<.pbc> is the standard extension for Parrot
bytecode. To execute the compiled bytecode, run it through the
F<parrot> interpreter:

  $ ./parrot fjord.pbc

This is, of course, a simple and contrived example. In the next few
chapters we will discuss more aspects of Parrot programming using
both PASM and PIR, and we will discuss some of the more advanced
features of Parrot that make it an interesting and attractive
programming platform.

=head2 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 it's
capabilities. None of these requirements or optional components are necessary
unless you are building Parrot from the source code.

=over 4

=item* C Compiler

Parrot can be built with a number of C compilers. Parrot is written using the
C89 standard, and the Parrot project officially supports the most recent
C89 compiler on major systems, including the most recent versions of Microsoft
C Compiler and the GNU Compiler Collection (GCC).

=item* make

Make is a program to manage and automate the build process. Unix-based systems
will typically have access to the C<make> command as part of the normal
development tools. Windows systems can get the C<nmake> utility to perform the
same task.

=item* Subversion

Subversion is the source control system that is used by the Parrot project.
You need subversion to checkout the latest version of the source code. You can
get subversion at L<http://subversion.tigris.org>, or on Linux systems you
can use the command

  sudo apt-get install subversion

=item* bison and flex

Bison and Flex are used to create the lexical analyzer and parser components
for the PIR compilers IMCC and PIRC. These are not necessary most of the time
unless you are planning to hack on IMCC and PIRC directly. On Linux systems you
can use the command

  sudo apt-get install bison flex

=item* ICU

ICU is a library for handling and manipulating Unicode text strings. Without
ICU libraries installed, you wont be able to use Unicode with your built
Parrot. On Linux systems you can get ICU with this command:

  sudo apt-get install libicu-dev

=item* GMP

GMP is a mathematics library for manipulating arbitrary precision and arbitrary
size numbers. GMP is used by the BigInt and BigNum PMCs, so without GMP you
won't have access to these data types. To get GMP on Linux systems, use the
command:

  sudo apt-get install libgmp3-dev

=item* Readline

The readline library allows some advanced behaviors on the command line such
as command history. You can get the readline library on Linux by using the
command:

  sudo apt-get install libreadline5-dev

=item* PCRE

PCRE is a library that provides access to the Perl 5 regular expression syntax.
In order to use these regular expressions, you will want to install PCRE. To
do that on Linux you use the command:

  sudo apt-get install libpcre3-dev

=item* GDBM

=item* PQ

=item* GLUT

GLUT is an interface to the OpenGL API. It enables programs running on Parrot
to have access to 3D graphics. To get GLUT on Linux systems you can use the
command:

  sudo apt-get install libglut3-dev

=back

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

=head2 Patch submission

Z<CHP-2-SECT-2.2.3>

X<Parrot;patch submission>
Parrot development proceeds through a continuous stream of patches.
Patches are the currency of exchange in the project--the unit of
work. Patches can fix bugs, add features, modify capabilities,
{'fraction_non_alphanumeric': 0.050352745884631345, 'fraction_numerical': 0.0053488264859132195, 'mean_word_length': 4.460221550855992, 'pattern_counts': {'":': 0, '<': 106, '<?xml version=': 0, '>': 106, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 15, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7467180', 'n_tokens_mistral': 5913, 'n_tokens_neox': 5625, 'n_words': 3330}