Author: allison
Date: Tue Feb 27 04:00:21 2007
New Revision: 17200
Modified:
trunk/docs/pdds/draft/pdd01_overview.pod
Log:
[pdd]: Update overview PDD to reflect current (and planned)
architecture.
Modified: trunk/docs/pdds/draft/pdd01_overview.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd01_overview.pod (original)
+++ trunk/docs/pdds/draft/pdd01_overview.pod Tue Feb 27 04:00:21 2007
@@ -1,4 +1,4 @@
-# Copyright (C) 2001-2004, The Perl Foundation.
+# Copyright (C) 2001-2007, The Perl Foundation.
# $Id$
=head1 NAME
@@ -7,51 +7,76 @@
=head1 ABSTRACT
-This PDD provides a high-level overview of the Parrot system.
+A high-level overview of the Parrot system.
-{{ NOTE: this needs to be more of an overall architecture plan. }}
-
-=head1 DESCRIPTION
+=head1 VERSION
-=head2 Major components
+$Revision$
-The Parrot system generally looks like this:
+=head1 DESCRIPTION
- +----------------------------------------------------+
- | Embedding App |
- +----------+------------+-------------+--------------+
- | | | | |
- | parser <-> compiler <-> optimizer <-> interpreter |
- | | | | |
- +----------+------------+-------------+--------------+
- | Extensions to Parrot |
- +----------------------------------------------------+
-
-=over 4
-
-=item Parser
-
-The parser takes source code of some sort and creates a syntax tree of that
-source.
-
-Different high level languages will generally have their own parser modules,
-implemented in whatever language is most convenient. For instance, we currently
-intend to write the parser for Perl 6 in Perl 6, to allow for easy extension.
-Generally there will be one parser per language, though there's no reason that
-there can't be multiple independent parsers.
+The following diagram gives a rough outline of the architecture of
+Parrot and the relationship between its major components, ranging from
+the components closest to the high-level languages targeting Parrot,
+down to those closest to the operating system.
+
+ +---------------------------------------------------+
+ | Parser Grammar Engine (PGE) |
+ +---------------------------------------------------+
+ | Tree Grammar Engine (TGE) |
+ +-------------------------+-------------------------+
+ | PASM | PIR |
+ | (assembly language) | (intermediate language) |
+ +-------------------------+-------------------------+
+ | Parrot Interpreter (IMCC) |
+ +---------------------------------------------------+
+ | Extensions |
+ +---------------------------------------------------+
+
+=head2 Parser
+
+While individual high-level languages may implement their own parser,
+most will use Parrot's parser grammar engine (PGE). The parser grammar
+engine compiles a parsing definition (.pg) file into an executable
+parser for the language. The resulting parser takes source code as input
+and creates a raw parse tree.
+
+Subsequent stages of compilation convert the raw parse tree into an
+annotated syntax tree. The tree grammar engine (TGE) compiles a
+transformation definition (.tg) file into an executable set of rules to
+transform data structures. In most compilers, the syntax tree goes
+through a series of transformations, starting with the raw parse tree,
+through a syntax tree that is close to the semantics of the HLL, and
+ending in a syntax tree that is close to the semantics of Parrot's
+bytecode. Some compilers will also insert optimizations stages into the
+compilation process between the common transformation stages.
+
+=head2 IMCC
+
+The intermediate code compiler (IMCC) is the main F<parrot> executable,
+and encapsulates several core low-level components.
+
+=head3 PASM & PIR parser
+
+This Bison and Flex based parser/lexer handles Parrot's assembly
+language, PASM, and the slightly higher-level language, PIR (Parrot
+Intermediate Representation).
-=item Bytecode compiler
+=head3 Bytecode compiler
The bytecode compiler module takes a syntax tree from the parser and emits an
unoptimized stream of bytecode. This code is suitable for passing straight to
the interpreter, though it is probably not going to be very fast.
-=item Optimizer
+Note that currently, the only way to generate bytecode is by first
+generating PASM or PIR.
+
+=head3 Optimizer
The optimizer module takes the bytecode stream from the compiler and optionally
the syntax tree the bytecode was generated from, and optimizes the bytecode.
-=item Interpreter
+=head3 Interpreter
The interpreter module takes the bytecode stream from either the optimizer or
the bytecode compiler and executes it. There must always be at least one
@@ -64,44 +89,54 @@
would take the bytecode stream and spit out Java bytecode instead of
interpreting it.
-=back
+=head3 Standalone pieces
+
+Each piece of IMCC can, with enough support hidden away (in the form of an
+interpreter for the parsing module, for example), stand on its own. This means
+it's feasible to make the parser, bytecode compiler, optimizer and interpreter
+separate executables.
-=head2 Independent subsystems
+This allows us to develop pieces independently. It also means we can
+have a standalone optimizer which can spend a lot of time groveling over
+bytecode, far more than you might want to devote to optimizing
+one-liners or code that'll run only once or twice.
-Parrot also has a number of subsystems that are independent of any single
-module.
+=head2 Subsystems
-=over 4
+The following subsystems are each responsible for a key component of
+Parrot's core functionality.
-=item ParrotIO subsystem
+=head3 I/O subsystem
-The ParrotIO subsystem provides source- and platform-independent asynchronous
-I/O to Parrot. The intent is to make Parrot (and any languages that run on it)
-independent of C's stdio system. (And good riddance--it sucks) How this maps
-to the OS's underlying I/O code is not generally Parrot's concern, and a
-platform isn't obligated to provide asynchronous I/O.
+The I/O subsystem provides source- and platform-independent synchronous
+and asynchronous I/O to Parrot. How this maps to the OS's underlying I/O
+code is not generally Parrot's concern, and a platform isn't obligated
+to provide asynchronous I/O.
-Additionally, the ParrotIO subsystem allows a program to push filters onto an
+Additionally, the I/O subsystem allows a program to push filters onto an
input stream if necessary, to manipulate the data before it is presented to a
program.
-=item Regex engine
+=head3 Regular expression engine
+
+The parser grammar engine (PGE) is also Parrot's regular expression
+engine. The job of the regular expression engine is to compile regular
+expression syntax (both Perl 5 compatible syntax and Perl 6 syntax) into
+classes, and apply the matching rules of the classes to strings.
-By providing a regular expression engine as a separate subsystem of Parrot, we
-intend to make it easily available to any language running on Parrot (cf. the
-Perl 5 regex engine, which is intimately linked to the perl core). The job of
-the regex engine is to turn regexes into objects, and apply those regex
-objects to strings.
+The regular expression engine is available to any language running on
+Parrot.
-=back
+=head3 Data transformation engine
-=head2 API levels
+The tree grammar engine (TGE) is also a general-purpose data
+transformation tool (somewhat similar to XSLT).
-=over 4
+=head2 API levels
-=item Embedding
+=head3 Embedding
-The embedding API is the set of calls exported to the embedding application.
+The embedding API is the set of calls exported to an embedding application.
This is a small, simple set of calls, requiring minimum effort to use.
The goal is to provide an interface that a competent programmer who is
@@ -110,78 +145,21 @@
intellectual effort. Generally it should take less than thirty minutes for a
simple interface, though more complete integration will take longer.
-Backwards binary compatibility at this level is guaranteed across the life of
-Parrot.
-
-=item Extensions
+=head3 Extensions
The extension API is the set of calls exported to Parrot extensions. They
provide access to most of the things an extension needs to do, while hiding the
implementation details. (So that, for example, we can change the way scalars
are stored without having to rewrite, or even recompile, an extension).
-Binary compatibility is a serious goal, though it may be broken if absolutely
-necessary.
-
-=item Guts
+=head3 Guts
The guts-level APIs are the routines used within a component. These aren't
guaranteed to be stable, and shouldn't be used outside a component. (For
example, an extension to the interpreter shouldn't call any of the parser's
internal routines).
-No binary compatibility is guaranteed, and routines here may be changed without
-notice.
-
-=back
-
-=head1 VARIATIONS ON A THEME
-
-One of the explicit goals of the Parrot project is to generate Java bytecode
-and .NET code, as well as to run on small devices such as the Palm. The
-modular nature of the Parrot system makes this reasonably straightforward.
-
-=over 4
-
-=item Parrot for small platforms
-
-For small platforms, any parser, compiler, and optimizer modules are replaced
-with a small bytecode loader module which reads in Parrot bytecode and passes
-it to the interpreter for execution. Note that the lack of a parser will limit
-the available functionality in some languages: for instance, in Perl, string
-eval, do, use, and require will not be available (although loading of
-precompiled modules via do, use, or require may be supported).
-
-=item Bytecode compilation
-
-One straightforward use of the Parrot system is to precompile a program into
-bytecode and save it for later use. Essentially, we would compile a program as
-normal, but then simply freeze the bytecode to disk for later loading.
-
-=item Perl in, Java (or whatever) out
-
-The previous section implicitly assumes that we will be emitting Parrot
-bytecode. However, there are other possibilities: we could translate the
-bytecode to Java bytecode or .NET code, or even to a native executable. In
-principle, Parrot could also act as a front end to other modular compilers
-such as gcc or HP's GEM compiler system.
-
-=item Standalone pieces
-
-Each piece of Parrot can, with enough support hidden away (in the form of an
-interpreter for the parsing module, for example), stand on its own. This means
-it's feasible to make the parser, bytecode compiler, optimizer and interpreter
-separate executables.
-
-This allows us to develop pieces independently--the first version of the Perl 6
-parser, for example, can be written mainly in perl 5 using an embedded
-interpreter. It also means we can have a standalone optimizer which can spend a
-lot of time groveling over bytecode, far more than you might want to devote to
-optimizing one-liners or code that'll run only once or twice.
-
-=back
-
-=head1 Target Platforms
+=head2 Target Platforms
The ultimate goal of Parrot is portability to more-or-less the same
platforms as Perl 5, including AIX, BeOS, BSD/OS, Cygwin, Darwin,
@@ -198,44 +176,40 @@
prior to the 1.0 release. As we approach the 1.0 release we will
actively seek porters for as many other platforms as possible.
-=head1 VERSION
-
-=head2 CURRENT
- Maintainer: Allison Randal
- Class: Meta
- PDD Number: 1
- Version: 1
- Status: Developing
- Last Modified: 6 December 2006
- PDD Format: 1
- Language: English
+=head1 LANGUAGE NOTES
-=head2 HISTORY
-
-=over
-
-=item 1.1
-
-12 Aug 2003
-
-=item 1.0
+One of the explicit goals of the Parrot project is to generate Java bytecode
+and .NET code, as well as to run on small devices such as the Palm. The
+modular nature of the Parrot system makes this reasonably straightforward.
-02 Jan 2001
+=head2 Parrot for small platforms
-=back
+For small platforms, any parser, compiler, and optimizer modules are replaced
+with a small bytecode loader module which reads in Parrot bytecode and passes
+it to the interpreter for execution. Note that the lack of a parser will limit
+the available functionality in some languages: for instance, in Perl, string
+eval, do, use, and require will not be available (although loading of
+precompiled modules via do, use, or require may be supported).
-=head1 CHANGES
+=head2 Bytecode compilation
-=over
+One straightforward use of the Parrot system is to precompile a program into
+bytecode and save it for later use. Essentially, we would compile a program as
+normal, but then simply freeze the bytecode to disk for later loading.
-=item 1.1
+=head2 Perl in, Java (or whatever) out
-Changed perl to Parrot where appropriate. Rewrote some sections to reflect the
-language agnostic nature of the project.
+The previous section implicitly assumes that we will be emitting Parrot
+bytecode. However, there are other possibilities: we could translate the
+bytecode to Java bytecode or .NET code, or even to a native executable. In
+principle, Parrot could also act as a front end to other modular compilers
+such as gcc or HP's GEM compiler system.
-=item 1.0
-None. First version
+=cut
-=back
+__END__
+Local Variables:
+ fill-column:78
+End:
