Add some overview of the compiler IRs

sorear · Nov 11, 2010 · 2e15054 · 2e15054
1 parent 4f676f7
commit 2e15054
Showing 1 changed file with 48 additions and 0 deletions.
diff --git a/docs/compiler.pod b/docs/compiler.pod
@@ -0,0 +1,48 @@
+=head1 Synopsis
+
+C<compiler.pod> - overview of Niecza compiler pipeline
+
+=head1 Description
+
+The Niecza compiler is currently completely static.  It is a Perl 5
+pipeline which converts Perl 6 code into C# code, then shells out
+to C<gmcs> to generate a .exe file.
+
+The compiler is structured as a series of phases, which do not match
+precisely with the source files.
+
+=head1 Intermediate representations
+
+=head2 Parse trees
+
+These are created by the viv-generated parser and are very ephemeral;
+with one exception they are always deconstructed immediately by the
+action methods.  Code to process them is entirely in C<Niecza::Actions>
+except for some heredoc code.
+
+=head2 Op trees
+
+This is the most worthy of the name "AST".  Op trees are built mostly
+from subclasses of C<Op>, with some C<Body> and C<RxOp> objects mixed
+in.  They contain unresolved symbol references, and are the most
+appropriate objects to return from macros once we have them.  These
+trees are primarily constructed in C<Niecza::Actions> during the "parse"
+phase, and are converted in-place into metamodel trees during "begin".
+
+=head2 Metamodel trees
+
+The metamodel trees are resolved to a specific data organization.  They
+make all typological relationships and scoping explicit.  They are
+constructed of many classes defined in C<src/Metamodel.pm>; function
+bodies are represented using C<Op> nodes, but it is important to keep
+in mind that at this stage C<Op> nodes represent pure code and have no
+declarative or scoping functions.  Most optimization passes work at this
+level.
+
+=head2 CgOp trees
+
+CgOp trees represent very concrete code.  They are constructed by
+methods on C<Op> and C<RxOp> objects and consumed by C<src/CgOpToCLROp.pm>,
+both during the "csharp" pass.  This part of the design is still
+very much in flux; see C<nam.pod> for a more forward-looking take
+on it.