= Pugs Apocryphon 1 -- Overview of the Pugs project

== What is this document about?

The [Pugs Apocrypha|http://svn.perl.org/perl6/pugs/trunk/docs/] are a series of
 documents, written in question/answer format, to explain the design and
 implementation of Pugs.  This document (PA01) is a higher-level overview of the
 project.

== What is Pugs?

Started in February 2005, [Pugs|http://pugscode.org/] is an
implementation of the Perl 6 language. [Autrijus
Tang|http://use.perl.org/%7Eautrijus/journal/] is responsible for the
design and development of Pugs with help from a group of committers and
contributors.

== What is Perl 6?

[Perl 6|http://dev.perl.org/perl6/] is the next major revision of Perl,
a context-sensitive, multi-paradigmatic, /practical/ programming
language, designed by a team led by Larry Wall. The Pugs project was 
[enthusiastically
welcomed|http://www.nntp.perl.org/group/perl.perl6.language/19263] by the Perl 6
team.

== Has Perl 6 been specified?

By December 2004, most of Perl 6 had been specified as a series of
[Synopses|http://dev.perl.org/perl6/synopsis/]. Although not considered
final, it is now stable enough to be implemented. Many of the Synopses
are based on Larry's [Apocalypses|http://dev.perl.org/perl6/apocalypse/]. 
Sometimes the design team releases
[Exegeses|http://dev.perl.org/perl6/exegesis/], which explain the Apocalypses.
Pugs adheres to the Synopses, referring to the Apocalypses or Exegeses when a
 Synopsis is unclear or imprecise.

== What does "Apocrypha" mean?

The word [Apocrypha|http://en.wikipedia.org/wiki/Apocrypha], from the
Greek word απκρυφος or "hidden",
refers to religious works that are not considered canonical, or part of
officially accepted scripture. The proper singular form in Greek is
"Apocryphon".

== What is the relationship between the Apocrypha and the Perl 6 design
documents?

Apocalypses and Synopses cover the Perl 6 language in general; Apocrypha
are specific to the Pugs implementation. Like the [Parrot Design
Documents|http://www.parrotcode.org/docs/pdd/], the Apocrypha will be
constantly updated according to the status of Pugs.

== Will Pugs implement the full Perl 6 specification?

Yes. Pugs always targets the latest revision of Perl 6 Synopses. As soon
as a new revision or a new Synopsis is published, incompatibilities
between Pugs and the new version will be considered bugs in Pugs.

== Is Pugs free software?

Yes. It is available under both 
[GPL version 2|http://svn.openfoundry.org/pugs/LICENSE/GPL-2] and 
[Artistic License version 2.0b5|http://svn.openfoundry.org/pugs/LICENSE/Artistic-2] 
Once the final version of Artistic 2.0 is released, Pugs will adopt it.

== Is Pugs funded by the Perl Foundation?

No. After receiving three [Perl Foundation
grants|http://www.perlfoundation.org/gc/grants/2003_autrijus.html] on
various projects, Autrijus decides it would be more helpful to donate
time to the Perl 6 project by hacking Pugs, rather than asking TPF for
money to do the same thing.

== Where can I download Pugs?

For the very latest version of Pugs, check out the source from the
[Subversion|http://svn.openfoundry.org/pugs/] or
[darcs|http://wagner.elixus.org/~autrijus/darcs/pugs] repositories. Periodic
releases are available on CPAN under the 
`[Perl6-Pugs|http://search.cpan.org/dist/Perl6-Pugs/]` distribution. 
(By the way, if you'd like to work offline with the Subversion
repository, [the `svk` client|http://svk.elixus.org/] may be of interest.
Using vanilla `svn` is fine, though.)

== How do I build Pugs?

Pugs uses the standard Makefile.PL build system, as detailed in the
`[README|http://svn.openfoundry.org/pugs/README]` file. Since Pugs is
written in Haskell, you will need [the Glasgow Haskell
Compiler (GHC)|http://haskell.org/ghc/] 6.4 or above. Please [download a
binary build|http://haskell.org/ghc/download_ghc_64.html] for your platform;
compiling GHC from source is a long, tedious process.

== What is Haskell?

[Haskell|http://haskell.org/] is a standardized, purely functional programming
language with builtin [lazy
 evaluation|http://en.wikipedia.org/wiki/Lazy_evaluation] capabilities. While
 there are several different implementations available, Pugs currently needs to
 be built with GHC, as it uses several GHC-specific features.

== What is GHC?

GHC is a state-of-the-art compiler and interactive environment, available under
[a BSD-style license|http://haskell.org/ghc/license.html]. Written in Haskell
itself, GHC can compile Haskell to bytecode, C code, and machine code (on some
platforms). GHC has an extensive library, numerous language extensions, and a
very capable optimizer (with some help from [a Perl 5
program|http://www.cse.unsw.edu.au/%7Echak/haskell/ghc/comm/the-beast/mangler.html]). 
As such, it provides an excellent platform to solve Perl 6's /bootstrapping
problem/.

== What is the Perl 6 bootstrapping problem?

The goal of the Perl 6 project is to be /self-hosting/: the Perl 6
compiler needs to be written in Perl 6 itself, and must parse Perl 6
source code with Perl 6 Rules, the next-generation pattern matching syntax for
Perl 6.  The generated code must also contain an evaluator that can execute Perl
6 code on the fly. The only way to break this cycle of dependency is by
first implementing some parts in other languages, then rewriting those
parts in Perl 6.

== What was the initial bootstrapping plan?

According to the 
[Parrot FAQ|http://search.cpan.org/dist/parrot/docs/faq.pod#Isn't_there_a_bootstrapping_problem?], 
the initial plan was to bootstrap via Perl 5: first extend Perl 5 to run on the
Parrot virtual machine (via `B::Parrot` or [Ponie|http://www.poniecode.org/]),
then implement the Perl 6 compiler in Perl 5, which will be translated to Perl 6
via a p5-to-p6 translator. However, although part of the Rules system was
prototyped in Perl 5 as
`[Perl6::Rules|http://search.cpan.org/dist/Perl6-Rules/]`, it was not mature
enough to build a compiler on. As such, the plan was revised to bootstrap via C
instead.

== What is the revised bootstrapping plan?

According to an early 2005
[proposal|http://www.perlfoundation.org/gc/grants/2005-p6-proposal.html], the
plan is to first implement the Rule engine in C (i.e. [the Perl Grammar Engine
(PGE)|http://cvs.perl.org/viewcvs/cvs-public/parrot/compilers/pge/]), use it to
parse Perl 6 into Parrot as an [abstract syntax
tree|http://en.wikipedia.org/wiki/Abstract_syntax_tree] (AST), and then
implement an AST evaluator as part of Parrot. Ponie and p5-to-p6 are still being
worked on, but they are no longer critical dependencies in the bootstrapping
process.

== How can Pugs help Perl 6 to bootstrap?

In a bootstrapping process, there are often many bottlenecks, which prevent
people from working on things that depend on them. For example, one cannot
easily write unit tests and standard libraries for Perl 6 without a working
Perl 6 implementation, or work on an AST evaluator without an AST interface.
Pugs solves such deadlocks by providing ready substitutes at various levels of
the process.

== How can Pugs help the Perl 6 language design?

Without a working implementation, it is very hard to spot
inconsistencies and corner cases in the specification. However, if a
design problem is found late in the implementation phase, it may require the
costly rearchitecture of everything else. By providing a working Perl 6
implementation, Pugs can serve as a proving ground, finding and resolving
problems as early as possible, as well as encourage more people to exercise Perl
6's features.

== Why did you choose Haskell?

Many Perl 6 features have very similar Haskell counterparts: Perl 6 Rules
correspond closely to 
[Parsec|http://www.cs.uu.nl/%7Edaan/download/parsec/parsec.html]; lazy
list evaluation is common in both languages; continuation support can be
modeled with the [ContT|http://www.nomaware.com/monads/html/contmonad.html]
monad transformer; and so on. This greatly simplified the prototyping
effort: the first working interpreter was released [within the first
week|http://use.perl.org/~autrijus/journal/23051], and by the [third
week|http://use.perl.org/~autrijus/journal/23335] a fully-fledged 
`[Test.pm|http://svn.openfoundry.org/pugs/lib/Perl6/lib/Test.pm]` 
module was available for unit testing.

== What is the relationship between Pugs and Parrot?

The plan is for Pugs to target Parrot PIR. This is
already possible; Pugs can target Parrot PIR using an experimental Parrot
backend, which is being improved steadily.

== Is Pugs a compiler or an interpreter?

Similar to Perl 5, Pugs first compiles Perl 6 program to an AST, then
executes it using the built-in evaluator. However, in the future Pugs
may also provide a compiler interface that supports different compiler
backends.

== Which compiler backends are available?  Will more be added?

Currently, there are three compiler backends available: Pugs, Parrot
(experimental) and Haskell. More backends may be added if people can work on
them (e.g. Perl 5 bytecode).

== Do you have a roadmap for Pugs development?

The major/minor version numbers of Pugs converge to 2*π; each
significant digit in the minor version represents a milestone. The
third digit is incremented for each release. The current milestones
are:

* 6.0: Initial release.
* 6.2: Basic IO and control flow elements; mutable variables; assignment.
* 6.28: Classes and traits.
* 6.283: Rules and Grammars.
* 6.2831: Type system and linking.
* 6.28318: Macros.
* 6.283185: Port Pugs to Perl 6, if needed.

== How portable is Pugs?

Pugs runs on Win32, Linux and many flavors of Unix systems. See GHC's
[porters list|http://haskell.org/ghc/contributors.html] and [download
page|http://haskell.org/ghc/download_ghc_622.html] for details.
Binaries for Windows 2000/XP are available as part of [the PXPerl
distribution|http://pixigreg.com/?pxperl].  There are plans to provide binaries
for other platforms as well eventually.

== How fast is Pugs?

The parser part of Pugs is very fast, due to its robust underpinning in
Parsec. However, the Pugs evaluator is currently not optimized at all:
dispatching is around 1000 operators per second on a typical PC, which
is nearly 100 times slower than Perl 5. Still, it is fast enough for
prototyping language features; if you need fast operations in Pugs,
please consider helping out by working on the Compiler backend.

== Is there a CPAN for Perl 6 modules?

No. The current preferred method for submitting Perl 6/Pugs modules is
to ask for a committer bit at openfoundry.org and add your module to
the Pugs source tree under the modules/ directory. It is also helpful to
include test suites with your modules as well, so we can know when they
work. 

However, all is not lost. If you are patient you can wait for
`Pugs::MakeMaker` and `Module::Install::Pugs` to come out on CPAN. Once
they are available individually on CPAN, you can begin submitting things
to CPAN, because that means we've figured out the distribution problem.
Of course, suggestions are always welcome.

== Can Pugs work with Perl 5 libraries?

Yes, Pugs can work with Perl 5 libraries. This requires that Pugs be compiled
with Perl 5 embedding. Pugs understands Perl 5 objects, classes and functions.
Pugs objects, classes and functions are also understood by Perl 5.
As such, these types can be used in round-trip callbacks.

Examples of working with Perl 5 may be found in [the source
tree|http://svn.openfoundry.org/pugs/t/unspecced/p5/].

== Can Pugs work with Haskell libraries?

Yes. Pugs can be compiled with
`[hs-plugins|http://www.cse.unsw.edu.au/%7Edons/hs-plugins/]` support, which
allows it to use Haskell libraries. It is also capable of dynamically loading
Haskell modules. Aside from this, inline Haskell can be evaluated using
`eval('...', :lang<haskell>)`.

In addition, at the basic level, you can statically link Haskell libraries into
Pugs primitives, by modifying a few lines in `Prim.hs`.

== Can Pugs work with C libraries?

Not yet. However, [HaskellDirect|http://www.haskell.org/hdirect/] seems to
provide an easy way to interface with C, CORBA and COM libraries, especially
when combined with `hs-plugins` (described above).

== I know Perl 5, but not Haskell. Can I help develop Pugs?

Sure! The standard libraries and unit tests that come with Pugs are
coded in Perl 6, and there is always a need for more tests and
libraries. All you need is basic familiarity with Perl 5, and a few
minutes to acquaint yourself with some small syntax changes. A ["Porting
HOWTO"|http://svn.openfoundry.org/pugs/docs/other/porting_howto] is also
available, which should help ease the transition. You'll
likely pick up some Haskell knowledge along the way, too.

== I know Haskell, but not Perl 5. Can I help develop Pugs?

Sure! Perl 6 and Haskell have many things in common, such as type-based
function dispatch, first-class functions, and currying, so picking up the
syntax is relatively easy. Since there are always some TODO tests for
features in need of implementation, it is never hard to find something
to do.

== I have learned some Perl 6. What can I do with Pugs?

Look at the `examples/` directory to see some sample programs. Some people
are already writing web applications and report systems with Pugs. If
you run into a missing feature in Pugs, you are encouraged to write TODO tests
for it (if there aren't any already) so that someone can implement it.

== Where can I learn more about Haskell?

[The Haskell homepage|http://www.haskell.org/] and 
[the Wiki|http://haskell.org/hawiki/] are good entry points. Of the
many online tutorials, [Yet Another Haskell
Tutorial|http://www.isi.edu/%7Ehdaume/htut/] is perhaps the most accessible.
Due to the ubiquitous use of Monad transformers in Pugs, [All About
Monads|http://www.nomaware.com/monads/html/] is also recommended. For books,
[Algorithms: A Functional Programming 
Approach|http://www.iro.umontreal.ca/%7Elapalme/Algorithms-functional.html], 
[Haskell: The Craft of Functional Programming|http://www.cs.kent.ac.uk/people/staff/sjt/craft2e/]
and [The Haskell School of Expression|http://haskell.org/soe/] are fine
introductory materials. Finally,
[the `#haskell` channel|irc://irc.freenode.net/haskell] on
[freenode|http://freenode.net] is always full of helpful and interesting people.

== Where can I learn more about Perl 6?

[The Perl 6 homepage|http://dev.perl.org/perl6/] provides
many online documents. Every week or two, a new Perl 6 list summary appears on
[Perl.com|http://www.perl.com/]; it is a must-read for people who wish to
follow Perl 6's progress. For books, [Perl 6 and Parrot 
Essentials|http://www.oreilly.com/catalog/059600737X/] and [Perl 6 
Now|http://www.apress.com/book/bookDisplay.html?bID=355] are both helpful.

== Where can I learn more about implementing programming languages?

[Types and Programming Languages|http://www.cis.upenn.edu/%7Ebcpierce/tapl/] is
an essential read; Pugs started out as a self-initiated study of the text, and
it continues to be an important guide during the implementation. Its sequel,
[Advanced Topics in Types and Programming
Languages|http://www.cis.upenn.edu/%7Ebcpierce/attapl/], is also invaluable. It
may also help to get acquainted with other multi-paradigmatic languages, such as
 [Mozart/Oz|http://www.mozart-oz.org/],
[Curry|http://www.informatik.unikiel.de/%7Emh/curry/] and
[O'Caml|http://www.ocaml.org/]. Finally, the detailed [GHC
commentary|http://www.cse.unsw.edu.au/%7Echak/haskell/ghc/comm/] describes how
GHC itself was implemented.

== I'd like to help. What should I do?

First, subscribe to the 
[perl6-compiler|http://nntp.perl.org/group/perl.perl6.compiler] 
mailing list by sending an empty mail to 
[perl6-compiler-subscribe@perl.org|mailto:perl6-compiler-subscribe@perl.org]. 
Next, join [the `#perl6` IRC channel|irc://irc.freenode.net/perl6] on
[freenode|http://freenode.net/] to find out what needs to be done.
Commit access is handed out liberally; contact the Pugs team on `#perl6` for
details. See you on IRC!