Permalink
Browse files

[docs] Document bytecode generation for PCT

This adds a simple document that gives the bare bones about how to use
newPOST and what to expect if you do.  The list of known issues is
very short, mostly because I haven't found a good way to generate a
comprehensive list.
  • Loading branch information...
1 parent 21ba7f8 commit f74f55fd9ef1cab3e68d3185395f98814ad3f79a @Benabik Benabik committed Aug 20, 2011
Showing with 98 additions and 0 deletions.
  1. +98 −0 docs/pct/bytecode.pod
View
98 docs/pct/bytecode.pod
@@ -0,0 +1,98 @@
+# Copyright (C) 2011 Parrot Foundation.
+
+=head1 NAME
+
+Compiling to Bytecode with the Parrot Compiler Tools
+
+=head1 DESCRIPTION
+
+This document describes the steps needed to use the Parrot Compiler Tools
+(PCT) to directly generate bytecode files (.pbc). This feature is both
+experimental and incomplete, but assistance from experienced language
+authors is requested to help find the limitations.
+
+=head1 GETTING STARTED
+
+If you have created a high-level language with PCT via
+C<mk_language_shell.pl> or by hand, then you're most of the way towards
+using this new feature. It requires no changes to the grammar or actions,
+as all the changes to the process occur after you hand off a PAST tree to
+the library.
+
+To generate bytecode directly, you need to alter the stages that your
+compiler runs. Generally this is found in C<src/HLLName/Compiler.pm> (in
+this, and all further examples, replace C<HLLName> with the name of
+your language (i.e. C<src/Squaak/Compiler.pm>). This file contains
+all the configuration for your compiler inside an C<INIT> block. To change
+from the default compilation chain to the new chain, add the following
+line:
+
+ HLLName::Compiler.stages(<parse past newpost pbc>);
+
+This assumes that your language is written in NQP, as generated by
+C<mk_language_shell.pl>. If you have replaced this file with another
+language or created your compiler by hand, you need to do the equivalent of
+the following PIR:
+
+ $P0 = get_hll_global ['HLLName'], 'Compiler' # Get compiler object
+ $P1 = split ' ', 'parse past newpost pbc'
+ $P0.'stages'($P1)
+
+=head1 NEW STAGES
+
+The above code replaces the post, pir, and evalpmc stages with two new
+ones described below:
+
+=over 4
+
+=item * newpost
+
+Uses C<PAST::NewCompiler> to convert the PAST tree from your actions into a
+"newPOST" tree. newPOST contains additional information required to
+generate bytecode and is not supposed to contain any raw PIR source.
+
+=item * pbc
+
+Uses C<POST::PBCCompiler> to create a Packfile from the PAST tree. This
+returns the main method from the source for execution by the compiler.
+Using C<--output file.pbc> will allow you to save the generated packfile to
+a file.
+
+=cut
+
+=head1 KNOWN ISSUES
+
+newPOST is known to only compile fairly simple PAST trees at the moment.
+As more specific issues are found, they should be added to this list, and
+as features are implemented, they should be removed.
+
+=over 4
+
+=item * Exceptions
+
+C<Null PMC access in find_method('new')> in C<PAST::Compiler.try>
+
+=item * Inline PIR
+
+Because PIR is not generated when using these stages, inline PIR can not be
+used. To add this, a more fine-grained PIR parser would need to be addthat
+outputs newPOST trees.
+
+=cut
+
+=head1 UNKNOWN ISSUES
+
+If attempting to compile your program, you encounter an error message and
+the backtrace includes C<parrot;POST;PBCCompiler>, then likely you have
+attempted to use something not yet implemented. Here are a few of the
+common errors:
+
+=over 4
+
+=item * Method 'type' not found for invocant of class 'String'
+
+This likely means that some portion of PIR text made its way into
+C<POST::PBCCompiler>. An additional override in C<PAST::NewCompiler> will
+probably be needed to replace/alter the generated POST tree.
+
+=cut

0 comments on commit f74f55f

Please sign in to comment.