Skip to content
Browse files

Add documentation versions 2.0.0 through 2.11.0

  • Loading branch information...
1 parent 827ad4e commit 5caefd00825806aa2ea830673f0670140b2a6aa4 @ayardley ayardley committed
Showing with 16,064 additions and 0 deletions.
  1. +123 −0 2.0.0/Makefile
  2. +24 −0 2.0.0/book/draft/README
  3. +321 −0 2.0.0/book/draft/appa_glossary.pod
  4. +138 −0 2.0.0/book/draft/appb_patch_submission.pod
  5. +318 −0 2.0.0/book/draft/appc_command_line_options.pod
  6. +93 −0 2.0.0/book/draft/appd_build_options.pod
  7. +72 −0 2.0.0/book/draft/appe_source_code.pod
  8. +215 −0 2.0.0/book/draft/ch01_introduction.pod
  9. +182 −0 2.0.0/book/draft/ch02_getting_started.pod
  10. +234 −0 2.0.0/book/draft/ch07_dynpmcs.pod
  11. +259 −0 2.0.0/book/draft/ch08_dynops.pod
  12. +2,923 −0 2.0.0/book/draft/ch10_opcode_reference.pod
  13. +227 −0 2.0.0/book/draft/ch11_directive_reference.pod
  14. +299 −0 2.0.0/book/draft/ch12_operator_reference.pod
  15. +292 −0 2.0.0/book/draft/chXX_hlls.pod
  16. +107 −0 2.0.0/book/draft/chXX_library.pod
  17. +128 −0 2.0.0/book/draft/chXX_testing_and_debugging.pod
  18. +215 −0 2.0.0/book/pct/ch01_introduction.pod
  19. +182 −0 2.0.0/book/pct/ch02_getting_started.pod
  20. +333 −0 2.0.0/book/pct/ch03_compiler_tools.pod
  21. +1,558 −0 2.0.0/book/pct/ch04_pge.pod
  22. +219 −0 2.0.0/book/pct/ch05_nqp.pod
  23. +114 −0 2.0.0/book/pir/ch01_introduction.pod
  24. +78 −0 2.0.0/book/pir/ch02_getting_started.pod
  25. +314 −0 2.0.0/book/pir/ch03_basic_syntax.pod
  26. +1,816 −0 2.0.0/book/pir/ch04_variables.pod
  27. +343 −0 2.0.0/book/pir/ch05_control_structures.pod
  28. +1,300 −0 2.0.0/book/pir/ch06_subroutines.pod
  29. +450 −0 2.0.0/book/pir/ch07_objects.pod
  30. +388 −0 2.0.0/book/pir/ch08_io.pod
  31. +394 −0 2.0.0/book/pir/ch09_exceptions.pod
  32. +783 −0 2.0.0/compiler_faq.pod
  33. +309 −0 2.0.0/configuration.pod
  34. +243 −0 2.0.0/debug.pod
  35. +400 −0 2.0.0/debugger.pod
  36. +154 −0 2.0.0/dev/byteorder.pod
  37. +229 −0 2.0.0/dev/c_functions.pod
  38. +127 −0 2.0.0/dev/debugging_with_msvc.pod
  39. +119 −0 2.0.0/dev/events.pod
  40. +41 −0 2.0.0/dev/headerizer.pod
Sorry, we could not display the entire diff because too many files (6,031) changed.
View
123 2.0.0/Makefile
@@ -0,0 +1,123 @@
+# ex: set ro:
+# DO NOT EDIT THIS FILE
+# Generated by Parrot::Configure::Compiler from config/gen/makefiles/docs.in
+
+# Copyright (C) 2001-2006, Parrot Foundation.
+# $Id$
+
+# Setup of some commands
+PERL := /usr/bin/perl
+CHMOD := $(PERL) -MExtUtils::Command -e ExtUtils::Command::chmod
+MKPATH := $(PERL) -MExtUtils::Command -e mkpath
+TOUCH := $(PERL) -MExtUtils::Command -e touch
+RM_F := $(PERL) -MExtUtils::Command -e rm_f
+RM_RF := $(PERL) -MExtUtils::Command -e rm_rf
+PERLDOC := /usr/bin/perldoc
+VERSION := 2.0.0-devel
+
+# long list of .pod files
+POD := ops/bit.pod ops/cmp.pod ops/core.pod ops/debug.pod ops/experimental.pod ops/io.pod ops/math.pod ops/object.pod ops/pmc.pod ops/set.pod ops/string.pod ops/sys.pod ops/var.pod
+
+#
+# Targets
+#
+
+# The default target
+all: packfile-c.pod $(POD)
+
+# This is a listing of all targets, that are meant to be called by users
+# Most of them are proxied in the root makefile parrot/Makefile
+help :
+ @echo ""
+ @echo "Following targets are available to the user:"
+ @echo ""
+ @echo " all: Generate documentation from .pod files or from the sources."
+ @echo " This is the default target."
+ @echo " clean: Remove the generated documentation."
+ @echo " html: Generate HTML documentation."
+ @echo " html-clean: Remove the generated HTML documentation."
+ @echo ""
+
+$(POD): doc-prep
+
+doc-prep:
+ $(MKPATH) ops
+ $(TOUCH) doc-prep
+
+packfile-c.pod: ../src/packfile.c
+ $(PERLDOC) -ud packfile-c.pod ../src/packfile.c
+
+clean:
+ $(RM_F) packfile-c.pod $(POD) doc-prep
+
+html: all
+ $(PERL) -I../lib ../tools/docs/write_docs.pl --silent --version=$(VERSION)
+
+html-clean:
+ $(RM_RF) html
+
+htmlhelp: html
+
+htmlhelp-clean:
+
+
+# the following part of the Makefile was built by 'config/auto/perldoc.pm'
+
+ops/bit.pod: ../src/ops/bit.ops
+ $(PERLDOC) -ud ops/bit.pod ../src/ops/bit.ops
+ $(CHMOD) 0644 ops/bit.pod
+
+ops/cmp.pod: ../src/ops/cmp.ops
+ $(PERLDOC) -ud ops/cmp.pod ../src/ops/cmp.ops
+ $(CHMOD) 0644 ops/cmp.pod
+
+ops/core.pod: ../src/ops/core.ops
+ $(PERLDOC) -ud ops/core.pod ../src/ops/core.ops
+ $(CHMOD) 0644 ops/core.pod
+
+ops/debug.pod: ../src/ops/debug.ops
+ $(PERLDOC) -ud ops/debug.pod ../src/ops/debug.ops
+ $(CHMOD) 0644 ops/debug.pod
+
+ops/experimental.pod: ../src/ops/experimental.ops
+ $(PERLDOC) -ud ops/experimental.pod ../src/ops/experimental.ops
+ $(CHMOD) 0644 ops/experimental.pod
+
+ops/io.pod: ../src/ops/io.ops
+ $(PERLDOC) -ud ops/io.pod ../src/ops/io.ops
+ $(CHMOD) 0644 ops/io.pod
+
+ops/math.pod: ../src/ops/math.ops
+ $(PERLDOC) -ud ops/math.pod ../src/ops/math.ops
+ $(CHMOD) 0644 ops/math.pod
+
+ops/object.pod: ../src/ops/object.ops
+ $(PERLDOC) -ud ops/object.pod ../src/ops/object.ops
+ $(CHMOD) 0644 ops/object.pod
+
+ops/pmc.pod: ../src/ops/pmc.ops
+ $(PERLDOC) -ud ops/pmc.pod ../src/ops/pmc.ops
+ $(CHMOD) 0644 ops/pmc.pod
+
+ops/set.pod: ../src/ops/set.ops
+ $(PERLDOC) -ud ops/set.pod ../src/ops/set.ops
+ $(CHMOD) 0644 ops/set.pod
+
+ops/string.pod: ../src/ops/string.ops
+ $(PERLDOC) -ud ops/string.pod ../src/ops/string.ops
+ $(CHMOD) 0644 ops/string.pod
+
+ops/sys.pod: ../src/ops/sys.ops
+ $(PERLDOC) -ud ops/sys.pod ../src/ops/sys.ops
+ $(CHMOD) 0644 ops/sys.pod
+
+ops/var.pod: ../src/ops/var.ops
+ $(PERLDOC) -ud ops/var.pod ../src/ops/var.ops
+ $(CHMOD) 0644 ops/var.pod
+
+
+
+# Local variables:
+# mode: makefile
+# End:
+# vim: ft=make:
View
24 2.0.0/book/draft/README
@@ -0,0 +1,24 @@
+The book will have the following chapters.
+
+1) Overview
+2) Getting Started
+3) Parrot Intermediate Representation (PIR)
+4) Compiler Tools (PCT)
+5) Grammar Engine (PGE)
+6) Grammar Actions (NQP)
+7) Dynamic C-level Objects (PMCs)
+8) Dynamic Opcodes
+9) Parrot Assembly Language (PASM)
+10) Instruction Reference
+11) Directive Reference
+12) Operator Reference
+Appendix A) Glossary
+Appendix B) Patch Submission
+Appendix C) Command-Line Options
+Appendix D) Build Options
+Appendix E) Source Code
+
+
+Top-level headings in each chapter (the chapter title) are level 1 headings.
+All sub-headings in the chapter are level 2 and below. All chapter files should
+contain the VIM suffix (which is a codingstd for all of the Parrot repo).
View
321 2.0.0/book/draft/appa_glossary.pod
@@ -0,0 +1,321 @@
+=pod
+
+=head1 Glossary
+
+Short descriptions of words and acronyms found in Parrot development.
+
+=over 4
+
+=item AST
+
+Abstract Syntax Tree: a data structure typically generated by a language
+parser.
+
+=item Continuations
+
+Think of continuations as an execution "context". This context includes
+everything local to that execution path, not just the stack. It is a snapshot
+in time (minus global variables). While it is similar to C's C<setjmp> (taking
+the continuation)/C<longjmp> (invoking the continuation), C<longjmp>'ing only
+works "down" the stack; jumping "up" the stack (ie, back to a frame that has
+returned) is bad. Continuations can work either way.
+
+We can do two important things with continuations:
+
+=over 4
+
+=item 1
+
+Create and pass a continuation object to a subroutine, which may recursively
+pass that object up the call chain until, at some point, the continuation can
+be called/executed to handle the final computation or return value. This is
+pretty much tail recursion.
+
+=item 2
+
+Continuations can be taken at an arbitrary call depth, freezing the call chain
+(context) at that point in time. If we save that continuation object into a
+variable, we can later reinstate the complete context by its "handle". This
+allows neat things like backtracking that aren't easily done in conventional
+stacked languages, such as C. Since continuations represent "branches" in
+context, it requires an environment that uses some combination of heap-based
+stacks, stack trees and/or stack copying.
+
+=back
+
+It is common in a system that supports continuations to implement
+L<co-routines|"Co-Routines"> on top of them.
+
+A continuation is a sort of super-closure. When you take a continuation, it
+makes a note of the current call stack and lexical scratchpads, along with the
+current location in the code. When you invoke a continuation, the system drops
+what it's doing, puts the call stack and scratchpads back, and jumps to the
+execution point you were at when the continuation was taken. It is, in effect,
+like you never left that point in your code.
+
+Note that, like with closures, it only puts the B<scratchpads> back in scope -
+it doesn't do anything with the values in the variables that are in those
+scratchpads.
+
+=item Co-Routines
+
+Co-routines are virtually identical to normal subroutines, except while
+subroutines always execute from their starting instruction to where they
+return, co-routines may suspend themselves (or be suspended asynchronously if
+the language permits) and resume at that point later. We can implement things
+like "factories" with co-routines. If the co-routine never returns, every time
+we call it, we "resume" the routine.
+
+A co-routine is a subroutine that can stop in the middle, and start back up
+later at the point you stopped. For example:
+
+ sub sample : coroutine {
+ print "A\n";
+ yield;
+ print "B\n";
+ return;
+ }
+
+ sample();
+ print "Foo!\n";
+ sample();
+
+will print
+
+ A
+ Foo!
+ B
+
+Basically, the C<yield> keyword says, "Stop here, but the next time we're
+called, pick up at the next statement." If you return from a co-routine, the
+next invocation starts back at the beginning. Co-routines remember all their
+state, local variables, and suchlike things.
+
+=item COW
+
+Copy On Write: a technique that copies strings lazily.
+
+If you have a string A, and make a copy of it to get string B, the two strings
+should be identical, at least to start. With COW, they are, because string A
+and string B aren't actually two separate strings - they're the same string,
+marked COW. If either string A or string B are changed, the system notes it and
+only at that point does it make a copy of the string data and change it.
+
+If the program never actually changes the string - something that's fairly
+common - the program need never make a copy, saving both memory and time.
+
+=item destruction
+
+Destruction is low level memory clean up, such as calling C<free> on
+C<malloc>ed memory. This happens after L<"finalization">, and if resources are
+adequate, may only happen as a side effect of program exit.
+
+=item DOD
+
+Dead Object Detection: the process of sweeping through all the objects,
+variables, and whatnot inside of Parrot, and deciding which ones are in use and
+which ones aren't. The ones that aren't in use are then freed up for later
+reuse. (After they're destroyed, if active destruction is warranted.)
+
+See also: L<"GC">
+
+=item finalization
+
+Finalization is high-level, user visible cleanup of objects, such as closing an
+associated DB handle. Finalization reduces active objects down to passive
+blocks of memory, but does not actually reclaim that memory. Memory is
+reclaimed by the related L<"destruction"> operation, as and when necessary.
+
+=item GC
+
+Garbage Collection: the process of sweeping through all the active objects,
+variables, and structures, marking the memory they're using as in use, and all
+other memory is freed up for later reuse.
+
+Garbage Collection and Dead Object Detection are separate in Parrot, since we
+generally chew through memory segments faster than we chew through objects.
+(This is a characteristic peculiar to Perl and other languages that do string
+processing. Other languages chew through objects faster than memory)
+
+See also: L<"DOD">
+
+=item HLL
+
+High-Level Language; Any of the languages that target the parrot virtual
+machine.
+
+=item ICU
+
+International Components for Unicode
+
+ICU is a C and C++ library that provides support for Unicode on a variety of
+platforms. It was distributed with parrot at one time, but current releases
+require you to get your own copy.
+
+L<http://oss.software.ibm.com/icu/index.html>
+
+=item IMCC
+
+Intermediate Code Compiler: the component of parrot that compiles PASM
+and PIR into bytecode.
+
+See also L<"PIR">.
+
+=item MRO
+
+Method resolution order
+
+=item NCI
+
+Native Call Interface: parrot's interface to native "C" libraries,
+without a C-compiler.
+
+=item NQP
+
+Not Quite Perl (6): designed to be a very small compiler for
+quickly generating PIR routines to create transformers for Parrot (especially
+HLL compilers).
+
+See also L<"PCT">.
+
+=item Packfile
+
+Another name for a PBC file, due to the names used for data structures in one
+of the early implementations in Perl 5.
+
+=item PAST
+
+Acronym for Parrot Abstract Syntax Tree, a set of classes that represent an
+abstract syntax tree.
+
+See also L<"PCT">.
+
+=item PBC
+
+Parrot Bytecode. The name for the "executable" files that can be passed to the
+Parrot interpreter for immediate execution (although PASM and IMC files can be
+executed directly, too).
+
+See also L<"Packfile">.
+
+=item PCT
+
+Parrot Compiler Toolkit: a complete set of tools and libraries
+that are designed to create compilers targeting Parrot. The principal
+components of PCT are PGE, PCT::HLLCompiler (a compiler driver), PAST classes,
+POST classes, PCT::Grammar (a base class for PGE grammars).
+
+In the ideal case, a language can be implemented by providing its parser
+(using Perl 6 rules) which is generated by PGE, and providing a module written
+in NQP that contains the I<actions> that are to be invoked during the parse.
+These actions can then create the appropriate PAST nodes. A PAST to PIR
+transformation already exists. Depending on the language, other phases can
+be added, or overridden (for instance, the PAST to PIR transformation).
+
+=item PIRC
+
+Acronym for PIR Compiler, a PIR compiler currently under development.
+The purpose is to reimplement the PIR language, which is currently
+implemented by IMCC. PIRC is written using a Bison and Flex grammar
+specification.
+
+=item PDD
+
+Parrot Design Document: documents that describe the features parrot must
+implement.
+
+=item PGE
+
+Parrot Grammar Engine.
+
+See also L<"PCT">.
+
+=item PIR
+
+Parrot Intermediate Representation: A medium-level assembly language for Parrot
+that hides messy details like register allocation so language compiler writers
+who target Parrot don't have to roll their own. Files have the
+extension C<.pir>.
+
+=item PMC
+
+Polymorphic Container: these classes are the primitives that
+HLLs use to represent their fundamental types, such as Perl's
+scalar values.
+
+=item Pod
+
+The preferred format for all kinds of documentation in Parrot.
+
+=item POST
+
+Parrot Opcode Syntax Tree: A set of classes that represent opcodes.
+
+See also L<"PCT">.
+
+=item Predereferencing
+
+=for comment
+XXX This section needs to be edited down.
+
+A bytecode transformation technique which reduces the amount of pointer
+dereferencing done in the inner loop of the interpreter by pre-converting
+opcode numbers into pointers to their opfuncs, and also converting the register
+numbers and constant numbers in the arguments to the ops into pointers.
+
+The original implementation by Gregor Purdy was posted on 2001-12-11. On one
+test system, it resulted in a 22% speed increase on a test program with a tight
+inner loop.
+
+L<http://archive.develooper.com/perl6-internals@perl.org/msg06941.html>
+
+On 2001-12-18, predereferencing got a speed boost (to about 47% faster than the
+regular DO_OP inner loop -- without compiler optimizations turned on). This was
+due to an off-list (actually over lunch) suggestion by John Kennedy that
+instead of pre-initializing the new copy of the bytecode with NULL pointers, we
+pre-initialize it with pointers to a pseudo-opfunc that does the
+predereferencing whenever it is encountered.
+
+On 2002-04-11, Jason Gloudon suggested combining aspects of the Computed Goto
+Core and the Prederef[erencing] Core.
+
+L<http://archive.develooper.com/perl6-internals@perl.org/msg07064.html>
+
+The week of 2003-02-09, Leopold Toetsch combined Computed Goto and
+Predereferencing to produce the CGP core.
+
+L<http://dev.perl.org/perl6/list-summaries/2003/p6summary.2003-02-09.html#Week_of_the_alternative_runloops>
+
+Later, on 2003-02-14, Leopold Totsch and Nicholas Clark combined the JIT and
+the Computed Goto Prederef cores to great effect.
+
+L<http://www.perl.com/pub/a/2003/02/p6pdigest/20030216.html>
+
+=item Run Core
+
+aka run loop, aka runcore. The way Parrot executes PBCs.
+See L<running.pod> for a list of available runcores, and how to tell
+parrot which one to use.
+
+=item TGE
+
+Tree Grammar Engine: a tool that can be used to generate tree transformers.
+
+=item vtable
+
+A table of operations attached to some data types, such as PMCs and strings.
+Vtables are used to avoid using switches or long C<if> chains to handle
+different data types. They're similar to method calls, except that their names
+are pre-selected, and there is no direct way to invoke them from PIR.
+
+=item Warnock's Dilemma
+
+The dilemma you face when posting a message to a public forum about something
+and not even getting an acknowledgment of its existence. This leaves you
+wondering if your problem is unimportant or previously addressed, if everyone's
+waiting on someone else to answer you, or if maybe your mail never actually
+made it to anyone else in the forum.
+
+=back
+
+=cut
View
138 2.0.0/book/draft/appb_patch_submission.pod
@@ -0,0 +1,138 @@
+=pod
+
+=head1 Patch submission
+
+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,
+remove cruft, and improve the suite of tests and the project
+documentation. If something needs to change, it will typically require
+the submission of a new patch.
+
+While anyone is free to submit a patch, only a small number of people have
+the ability to apply patches to the central Parrot repository.
+These people are called I<committers>. By allowing all people to get
+involved through patch submission and testing, the project can harness
+the efforts of a large group but still keep the same high quality
+as a small group of experienced developers.
+
+Every submitted patch is automatically forwarded to the p2 list where
+it's subject to peer review. Small patches typically spark little debate,
+and can be well-tested on many platforms before being committed to the
+repository. Patches tend to be small modular changes, which makes for
+easy testing and evaluation. Occasionally a large feature such as an entire
+language implementation is submitted in a single patch, but these are the
+exceptions.
+
+Submitting a patch is fairly straightforward. You create a file that
+lists all your changes, a diff or a patch, and email it to the ticket
+tracking system at U<parrotbug@parrotcode.org>. It's important to make
+sure your patch and your email have descriptive titles so that the
+committers and testers have a better idea about what it does. The body of
+your email should also include a good description about what you changed
+and why.
+
+It's important that you create your patches from a checked-out subversion
+repository, not from a tarball or a snapshot. This way, you can ensure
+that your diff is made against the latest version of the files. If you patch
+an old version, the problem may have already been resolved! Make sure
+the paths listed in the patch match those in the repository. There are two
+methods of creating patches that will do this for you. You can make changes
+directly in your checked-out copy of the subversion repository and
+then create diffs using the command C<svn diff>. Alternatively, you can
+make a copy of the repository and then create diffs between the two
+copies with the C<diff -u> command:
+
+ diff -u parrot/README parrot_changed/README
+
+Either method is fine, and both are equally common on p2. Your
+working style and the types of changes you make--small and modular
+versus large and sweeping--will influence which method you choose.
+
+Next, when you're making changes, take some extra time to consider how
+your patch affects the rest of the system. If your patch adds a new
+file, patch the main F<MANIFEST> file to include it. If you add a new
+feature, make sure to write tests for it. If you fix a bug, add a test
+to prove that it's fixed. See "Writing Tests" in Chapter
+9 for more on writing tests for Parrot. Tests are very important for
+Parrot development, and writing good tests is a valuable skill for
+developers to have. Before you submit a patch always recompile the
+system yourself with the patch included and run all tests to prove that
+it works. You can build and test Parrot completely by running the
+following commands:
+
+ make clean
+ perl Configure.pl
+ make
+ make test
+
+Consider the people who will review and apply your patch, and try
+to make their jobs easier. Patch filenames should be as descriptive as
+possible: F<fix_readme_aardvark_typo.patch> is far better than
+F<README.patch>. An attached file is better than a diff pasted into an
+email, because it can be applied without manual editing. The
+conventional extension for patch files is F<.patch>.
+
+In the email message, always start the subject with "[PATCH]", and
+make the subject as clear as possible: "[PATCH] misspelled aardvark in
+main README file" is better than "[PATCH] typo". The body of the
+message should clearly explain what the patch is supposed to do and
+why you're submitting it. Make a note if you're adding or deleting
+files so they won't be missed.
+
+Here is a good example of a patch submission using the subversion diff
+method (an actual patch from p2). It's short, sticks to the point, and
+clearly expresses the problem and the solution. The patch filename and
+the subject of the message are both descriptive:
+
+=for author
+
+Possible alternates: ticket #23501, #24053 (not from top level)
+
+=end for
+
+ Subject: [PATCH] Pointers in List_chunk not initialized
+ From: Bruce Gray
+
+ On Win32, these tests are segfaulting due to invalid
+ pointers in List_chunk structs:
+ t/op/string.t 97-98
+ t/pmc/intlist.t 3-4
+ t/pmc/pmc.t 80
+
+ The problem is caused by list.c/allocate_chunk not
+ initializing the pointers. This patch corrects the problem.
+
+ --
+ Hope this helps,
+ Bruce Gray
+
+With the attached file F<list_chunk_initialize.patch>:
+
+
+ Index: list.c
+ =========================================
+ RCS file: /cvs/public/parrot/list.c,v
+ retrieving revision 1.23
+ diff -u -r1.23 list.c
+ --- list.c 27 Dec 2002 09:33:11 -0000 1.23
+ +++ list.c 28 Dec 2002 03:37:35 -0000
+ @@ -187,6 +187,10 @@
+ Parrot_block_GC_sweep(interpreter);
+ chunk = (List_chunk *)new_bufferlike_header(interpreter, sizeof(*chunk));
+ chunk->items = items;
+ + chunk->n_chunks = 0;
+ + chunk->n_items = 0;
+ + chunk->next = NULL;
+ + chunk->prev = NULL;
+ Parrot_allocate_zeroed(interpreter, (Buffer *)chunk, size);
+ Parrot_unblock_GC_mark(interpreter);
+ Parrot_unblock_GC_sweep(interpreter);
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
318 2.0.0/book/draft/appc_command_line_options.pod
@@ -0,0 +1,318 @@
+=pod
+
+=head1 Command-Line Options
+
+Z<CHP-13-SECT-4>
+
+X<command-line options (Parrot)>
+X<Parrot;command-line options>
+X<running.pod file>
+Since Parrot is both an assembler and a bytecode interpreter, it
+has options to control both behaviors. Some options may have changed
+by the time you read this, especially options related to debugging and
+optimization. The document F<imcc/docs/running.pod> should
+have the latest details. Or just run F<parrot --help>.
+
+=head2 General Usage
+
+Z<CHP-13-SECT-4.1>
+
+ parrot [options] file [arguments]
+
+The R<file> is either an F<.pir> or F<.pasm> source file or a
+Parrot bytecode file. Parrot creates an C<Array> object to hold the
+command-line R<arguments> and stores it in C<P5> on program start.
+
+=head2 Assembler Options
+
+Z<CHP-13-SECT-4.2>
+
+=over 4
+
+=item -a, --pasm
+
+X<Parrot;assembler options>
+Assume PASM input on C<stdin>. When Parrot runs a source file with a
+F<.pasm> extension, it parses the file as pure PASM code. This switch
+turns on PASM parsing (instead of the default PIR parsing) when a
+source file is read from C<stdin>.
+
+=item -c,--pbc
+
+Assume PBC file on C<stdin>. When Parrot runs a bytecode file with a
+F<.pbc> extension, it immediately executes the file. This option tells
+Parrot to immediately execute a bytecode file piped in on C<stdin>.
+
+=item -d,--debug [R<hexbits>]
+
+Turn on debugging output. The C<-d> switch takes an optional argument,
+which is a hex value of debug bits. The individual bits are shown in
+Table 11-3. When R<hexbits> isn't specified,
+the default debugging level is 0001. If R<hexbits> is separated
+from the C<-d> switch by whitespace, it has to start with a number.
+
+=begin table picture Debug bits
+
+Z<CHP-13-TABLE-3>
+
+=headrow
+
+=row
+
+=cell Description
+
+=cell Debug bit
+
+=bodyrows
+
+=row
+
+=cell DEBUG_PARROT
+
+=cell 0001
+
+=row
+
+=cell DEBUG_LEXER
+
+=cell 0002
+
+=row
+
+=cell DEBUG_PARSER
+
+=cell 0004
+
+=row
+
+=cell DEBUG_IMC
+
+=cell 0008
+
+=row
+
+=cell DEBUG_CFG
+
+=cell 0010
+
+=row
+
+=cell DEBUG_OPT1
+
+=cell 0020
+
+=row
+
+=cell DEBUG_OPT2
+
+=cell 0040
+
+=row
+
+=cell DEBUG_PBC
+
+=cell 1000
+
+=row
+
+=cell DEBUG_PBC_CONST
+
+=cell 2000
+
+=row
+
+=cell DEBUG_PBC_FIXUP
+
+=cell 4000
+
+=end table
+
+X<Parrot;debugging bits>
+X<debugging bits (Parrot)>
+To produce a huge output on C<stderr>, turn on all the debugging bits:
+
+ $ parrot -d 0ffff ...
+
+
+=item --help-debug
+
+Show debug option bits.
+
+=item -h,--help
+
+Print a short summary of options to C<stdout> and exit.
+
+=item -o R<outputfile>
+
+Act like an assembler. With this switch Parrot won't run code unless
+it's combined with the C<-r> switch. If the name of R<outputfile> ends
+with a F<.pbc> extension, Parrot writes a Parrot bytecode file. If
+R<outputfile> ends with a F<.pasm> extension, Parrot writes a PASM
+source file, even if the input file was also PASM. This can be handy
+to check various optimizations when you run Parrot with the C<-Op>
+switch.
+
+=item -r,--run-pbc
+
+Immediately execute bytecode. This is the default unless C<-o> is
+present. The combination of C<-r> C<-o> C<output.pbc> writes a
+bytecode file and executes the generated PBC.
+
+=item -v,--verbose
+
+One C<-v> switch (C<imcc> C<-v>) shows which files are worked on and
+prints a summary of register usage and optimization statistics. Two
+C<-v> switches (C<imcc> C<-v> C<-v>) also prints a line for each
+individual processing step.
+
+=item -y,--yydebug
+
+Turn on C<yydebug> for F<yacc>/F<bison>.
+
+=item -E,--pre-process-only
+
+Show output of macro expansions and quit.
+
+=item -V,--version
+
+Print the program version to C<stdout> and exit.
+
+=item -Ox
+
+Turn on optimizations. The flags currently implemented are shown in
+Table 11-4.
+
+X<Parrot;optimizations>
+X<optimizations (Parrot)>
+
+=begin table picture Optimizations
+
+Z<CHP-13-TABLE-4>
+
+=headrow
+
+=row
+
+=cell Flag
+
+=cell Meaning
+
+=bodyrows
+
+=row
+
+=cell C<-O0>
+
+=cell No optimization (default).
+
+=row
+
+=cell C<-O1>
+
+=cell Optimizations without life info (e.g. branches and constants).
+
+=row
+
+=cell C<-O2>
+
+=cell Optimizations with life info.
+
+=row
+
+=cell C<-Oc>
+
+=cell Optimize function call sequence.
+
+=row
+
+=cell C<-Op>
+
+=cell Rearrange PASM registers with the most-used first.
+
+=end table
+
+=back
+
+=head2 Runcore Options
+
+Z<CHP-13-SECT-4.3>
+
+X<Parrot;bytecode interpreter options>
+X<bytecode interpreter options (Parrot)>
+X<computed goto core>
+X<fast core>
+The interpreter options are mainly for selecting which run-time core to
+use for interpreting bytecode. The current default is the I<computed
+goto core> if it's available. Otherwise the I<fast core> is used.
+
+=over 4
+
+=item -R slow
+
+Run with the I<slow core>
+
+=item -R bounds
+
+Activate bounds checking. This also runs with the I<slow core> as a
+side effect.
+
+=item -R fast
+
+Run with the I<fast core>.
+
+=item -R cgoto
+
+Run the I<computed goto core> (CGoto).
+
+=item -R cgp
+
+Run with the I<CGoto-Prederefed> core.
+
+=item -R switch
+
+Run with the I<Switched core>.
+
+=item -R gcdebug
+
+Performs a full GC run before every op dispatch
+(good for debugging GC problems)
+
+=item -p,--profile
+
+Activate profiling. This prints a summary of opcode usage and
+execution times after the program stops. It also runs within the
+I<slow core>.
+
+=item -t,--trace
+
+Trace execution. This also turns on the I<slow core>.
+
+=item -w,--warnings
+
+Turn on warnings.
+
+=item -G,--no-gc
+
+Turn off GC. This is for debugging only.
+
+=item -.,--wait
+
+Wait for a keypress before running.
+
+=item --leak-test,--destroy-at-end
+
+Cleanup up allocated memory when the final interpreter is destroyed.
+C<Parrot> destroys created interpreters (e.g. threads) on exit but
+doesn't normally free all memory for the last terminating interpreter,
+since the operating system will do this anyway. This can create false
+positives when C<Parrot> is run with a memory leak detector. To prevent
+this, use this option.
+
+=back
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
93 2.0.0/book/draft/appd_build_options.pod
@@ -0,0 +1,93 @@
+=pod
+
+=head1 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 its
+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 through one of the
+common packaging systems.
+
+=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.
+
+=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.
+
+=item * GMP
+
+GMP is a mathematics library for manipulating arbitrary precision and
+arbitrary size numbers. GMP is an optional library used by the BigInt
+and BigNum PMCs.
+
+=item * Readline
+
+The readline library allows some advanced behaviors on the command line such
+as command history.
+
+=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 the full set of 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
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
72 2.0.0/book/draft/appe_source_code.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head3 Use the source
+
+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 option 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
+available from U<http://www.parrot.org/download>.
+
+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<https://trac.parrot.org> username, and need to be approved by a
+Metacommitter. 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>.
+
+There are a number of existing language implementations for Parrot:
+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 these languages and where to find them.
+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 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 Chapter 3, Chapter 5, and Chapter 7
+respectively.
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
215 2.0.0/book/draft/ch01_introduction.pod
@@ -0,0 +1,215 @@
+=pod
+
+=head1 Introduction
+
+Parrot is a language-neutral virtual machine for dynamic languages such as
+Ruby, Python, PHP, and Perl. It hosts a powerful suite of compiler tools
+tailored to dynamic languages and a next generation regular expression engine.
+Its architecture is fundamentally different than existing virtual machines such
+as the JVM or CLR, with optimizations for dynamic languages included, a
+register-based system rather than stack-based, and the use of continuations as
+the core means of flow control.
+
+The name "Parrot" was inspired by Monty Python's Parrot sketch. As an April
+Fools' Day joke in 2001, Simon Cozens published "Programming Parrot", a
+fictional interview between Guido van Rossum and Larry Wall detailing their
+plans to merge Python and Perl into a new language called Parrot
+(U<http://www.perl.com/pub/a/2001/04/01/parrot.htm>).
+
+=head2 Parrot Resources
+
+The starting point for all things related to Parrot is the main website
+U<http://www.parrot.org/>. The site lists additional resources, well as recent
+news and information about the project and the Parrot Foundation, which holds
+the copyright over Parrot and helps guide development and the community.
+
+=head3 Documentation
+
+Parrot includes extensive documentation in the distribution. The full
+documentation for the latest release is available online at
+U<http://docs.parrot.org/>.
+
+=head3 Mailing Lists
+
+X<parrot-dev (Parrot mailing list)>
+X<mailing lists>
+
+The primary mailing list for Parrot is I<parrot-dev@lists.parrot.org>. If
+you're interested in getting involved in development, you may also want to
+follow the I<parrot-commits> and I<parrot-tickets> lists. Information on all
+the Parrot mailing lists and subscription forms for each is available at
+U<http://lists.parrot.org/mailman/listinfo>.
+
+The archives for I<parrot-dev> are also available on Google Groups at
+U<http://groups.google.com/group/parrot-dev> and via NNTP at
+U<nntp://news.gmane.org/gmane.comp.compilers.parrot.devel>.
+
+=head3 IRC
+
+X<#parrot (Parrot IRC channel)>
+X<IRC channel (#parrot)>
+
+Parrot developers and users congregate on IRC at C<#parrot> on the
+U<irc://irc.parrot.org> server. It's a good place to get real-time answers to
+questions or see how things are progressing.
+
+=head3 Issue Tracking & Wiki
+
+X<trac.parrot.org website>
+X<issue tracking (trac.parrot.org)>
+
+Parrot developers track issues with a Trac site at U<https://trac.parrot.org/>.
+Users can submit new tickets and track the status of existing tickets. The
+site also includes a wiki used in project development, a source code browser,
+and the project roadmap.
+
+=head2 Parrot Development
+
+X<development cycles>
+
+Parrot's first release occurred in September 2001. It reached 1.0 in March
+2009. The Parrot project makes releases on the third Tuesday of each month. Two
+releases a year E<mdash> occuring every January and July E<mdash> are
+"supported" releases intended for production use. The other ten releases are
+development releases for language implementers and testers.
+
+Development proceeds in cycles around releases. Activity just before a release
+focuses on closing tickets, fixing bugs, reviewing documentation, and preparing
+for the release. Immediately after the release, larger changes occur, such as
+merging branches, adding large features, or removing deprecated features. This
+allows developers to ensure that changes have sufficient testing time before
+the next release. Releases also encourage feedback as casual users and testers
+explore the newest versions.
+
+=head2 The Parrot Team
+
+Parrot developers fulfill several rules according to their skills and interests.
+
+=over 4
+
+=item Architect
+
+X<architect role>
+
+The architect has primary responsibility for setting the overall direction of
+the project, facilitating team communication, and explaining and evaluating
+architectural issues. The architect makes design decisions and documents them
+in Parrot Design Documents, and oversees design and documentation work
+delegated to other members of the team to provide a coherent vision across the
+project. The architect also works with the release managers to develop and
+maintain the release schedule. Allison Randal currently leads the Parrot
+project as architect.
+
+=item Release Managers
+
+X<release manager role>
+
+Release managers manage and produce monthly releases according to the release
+schedule. Parrot has multiple release managers who rotate the responsibility
+for each monthly release. The release managers develop and maintain the release
+schedule jointly with the project architect.
+
+=item Metacommitter
+
+X<metacommitter role>
+
+Metacommitters manage commit access to the Parrot repository. Once a
+contributor is selected for commit access, a metacommitter gives the new
+committer access to the SVN repository and the bugtracker. The architect is a
+metacommitter, but other team members also hold this role.
+
+=item Committer
+
+X<committer role>
+
+Contributors who submit numerous, high-quality patches may be considered to
+become a committer. Committers have commit access to the full Parrot
+repository, though they often specialize on particular parts of the project.
+Contributors may be considered for commit access either by being nominated by
+another committer, or by requesting it.
+
+=item Core Developer
+
+X<core developer role>
+
+Core developers develop and maintain core subsystems such as the I/O
+subsystem, the exceptions system, or the concurrency scheduler.
+
+=item Compiler Developer
+
+X<compiler developer role>
+
+Compiler developers develop and maintain one or more Parrot front-end
+compilers such as IMCC, PIRC, PGE and TGE.
+
+=item High-Level Language Developer
+
+X<HLL developer role>
+
+Developers who work on any of the high-level languages that target
+ParrotE<mdash>such as Lua, Perl, PHP, Python, Ruby, or TclE<mdash>are
+high-level language developers. The Parrot repository includes a few example
+languages. A full list of languages is available at
+U<https://trac.parrot.org/parrot/wiki/Languages>.
+
+=item Build Manager
+
+X<build manager role>
+
+Build managers maintain and extend configuration and build subsystems.
+They review smoke reports and attempt to extend platform support.
+
+=item Tester
+
+X<tester role>
+
+Testers develop, maintain, and extend the core test suite coverage and testing
+tools. Testers are also responsible for testing goals, including complete
+coverage of core components on targeted platforms.
+
+=item Patch Monsters
+
+X<patch monster role>
+
+Hackers and developers submit patches to Parrot every day, and it takes a keen
+eye and a steady hand to review and apply them all. Patch monsters check
+patches for conformance with coding standards and desirability of features,
+rework them as necessary, verify that the patches work as desired, and apply
+them.
+
+=item Cage Cleaners
+
+X<cage cleaner role>
+
+The cage cleaners ensure that development follows the project's coding
+standards, documentation is complete and accurate, all tests function properly,
+and new users have accurate and comprehensive coding examples. A special class
+of Trac tickets is available for these tasks. Cage cleaning tasks run the
+gamut from entry-level to advanced; this is a good entry point for new users
+to work on Parrot.
+
+=item General Contributor
+
+X<contributor role>
+
+Contributors write code or documentation, report bugs, take part in email or
+online conversations, or contribute to the project in other ways. All volunteer
+contributions are appreciated.
+
+=back
+
+=head2 Licensing
+
+X<license>
+
+The Parrot foundation supports the Parrot development community and holds
+trademarks and copyrights to Parrot. The project is available under the
+Artistic License 2.0, allowing free use in commercial and open source/free
+software contexts.
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
182 2.0.0/book/draft/ch02_getting_started.pod
@@ -0,0 +1,182 @@
+=pod
+
+=head1 Getting Started
+
+Before you can use Parrot, you have to get it running on your machine.
+
+=head2 Installing Parrot
+
+The simplest way to install Parrot is to use a pre-compiled binary for your
+operating system or distribution. Packages are available for many packaging
+systems, including Debian, Ubuntu, Fedora, Mandriva, FreeBSD, Cygwin, and
+MacPorts. The Parrot website lists all known packages at
+U<http://www.parrot.org/download>. A binary installer for Windows is also
+available at U<http://parrotwin32.sourceforge.net/>.
+
+If packages aren't available on your system, download the latest supported
+release from U<http://www.parrot.org/release/supported>.
+
+You need a C compiler and a make utility to build Parrot from source code --
+usually C<gcc> and C<make>, but Parrot can build with standard compiler
+toolchains on different operating systems. Perl 5.8 is also a prerequiste for
+configuring and building Parrot.
+
+If you have these dependencies installed, build the core virtual machine and
+compiler toolkit and run the standard test suite with the commands:
+
+ $ B<perl Configure.pl>
+ $ B<make>
+ $ B<make test>
+
+By default, Parrot installs to directories F<bin/>, C<lib/>, et cetera under
+the prefix F</usr/local>. If you have privileges to write to these
+directories, install Parrot with:
+
+ $ B<make install>
+
+To install Parrot beneath a different prefix, use the C<--prefix> option to
+C<Configure.pl>:
+
+ $ B<perl Configure.pl --prefix=/home/me/parrot>
+
+If you intend to I<develop> -- not just I<use> -- a language on Parrot, install
+the Parrot developer tools as well:
+
+ $ B<make install-dev>
+
+=head2 Running Parrot
+
+Once you've installed Parrot, run it. Create a test file called F<news.pasm>.
+C<.pasm> files contain Parrot Assembly Language (PASM) instructions; this is a
+low-level language native to the Parrot virtual machine.
+
+=begin PASM
+
+ say "Here is the news for Parrots."
+ end
+
+=end PASM
+
+Now run this file with:
+
+ $ B<parrot news.pasm>
+
+which will print:
+
+ Here is the news for Parrots.
+
+=head2 Running a Language on Parrot
+
+Next, try out one of Parrot's high-level languages. Create a test file
+called F<more_news.nqp>:
+
+ say "No parrots were involved in an accident on the M1 today..."
+
+Then run it as:
+
+ $ nqp more_news.nqp
+
+which will print:
+
+ No parrots were involved in an accident on the M1 today...
+
+=head2 What Next?
+
+This book describes Parrot in terms of tasks it supports. You may pick and
+choose chapters based on your area of interest:
+
+=over 4
+
+=item Chapter 3, I<Parrot Intermediate Representation>
+
+Parrot Intermediate Representation (PIR) is a mid-level language native to the
+Parrot virtual machine s commonly used for writing extensions and tools for
+Parrot.
+
+=item Chapter 4, I<Compiler Tools>
+
+The Parrot Compiler Toolkit (PCT) provides a common infrastructure and
+utilities for implementing languages on Parrot.
+
+=item Chapter 5, I<Grammar Engine>
+
+The Parrot Grammar Engine (PGE) is a powerful regular expression engine and
+recursive descent parser. PGE is part of the compiler tools; understanding PGE
+is essential to implementing a language on Parrot.
+
+=item Chapter 6, I<Grammar Actions>
+
+NQP (Not Quite Perl) is a lightweight language loosely inspired by Perl 6. NQP
+is part of the compiler tools used for transforming a Parrot-hosted language
+into instructions for Parrot to execute.
+
+=item Chapter 7, I<Dynamic PMCs>
+
+=for author
+
+This chapter suggests the need for a chapter on core PMCs. Alternately, this
+chapter could cover PMCs in general and dynpmcs as a special case of PMCs.
+
+=end for
+
+Parrot allows language developers to extend Parrot's core data types to suit
+the needs of advanced languages.
+
+=item Chapter 8, I<Dynamic Opcodes>
+
+=for author
+
+The same point applies for ops and dynops.
+
+=end for
+
+Parrot allows language developers to extend Parrot's core instruction set --
+again to suit the needs of advanced languages.
+
+=item Chapter 10, I<Instruction Reference>
+
+Parrot's standard instruction set provides powerful behavior for primitive
+operations, control flow, object orientation, exception handling, and more.
+
+=item Chapter 11, I<Directive Reference>
+
+Parrot supports directives used within PIR and PASM code to change the behavior
+of code and to control what happens in bytecode.
+
+=item Chapter 13, I<Operator Reference>
+
+PIR provides several higher-level operators as a convenience to programmers and
+code generators.
+
+=item Appendix A, I<Glossary>
+
+Parrot and its environment have common jargon.
+
+=item Appendix B, I<Command-Line Options>
+
+Parrot supports several flags to control execution modes, debugging, library
+loading, and more.
+
+=item Appendix C, I<Build Options>
+
+Parrot's configuration process gives administrators and developers tremendous
+control over the build system.
+
+=item Appendix D, I<Source Code>
+
+Parrot's source code is organized along logical lines -- logical, once you know
+the layout.
+
+=item Appendix E, I<Patch Submission>
+
+Parrot depends on the combined efforts of numerous volunteers. Your
+contributions are very welcome.
+
+=back
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
234 2.0.0/book/draft/ch07_dynpmcs.pod
@@ -0,0 +1,234 @@
+=pod
+
+=head1 Dynamic C-level Objects
+
+Z<CHP-11>
+
+PMCs are one of the four fundamental data types in Parrot, and definitely one
+of the most useful. A PMC can contain a single scalar value (integer, floating
+point number, string), an array of values, a subroutine, a namespace, or an
+entire list of other data types as well. PMCs are the basis for all higher
+order data types in Parrot, and are flexible enough to be used for any
+purpose that an HLL needs.
+
+All the common PMC types are included in the Parrot repository and built directly
+into libparrot and the parrot executable. However, the system is not rigid; new
+PMC types can be defined externally and loaded into Parrot at a later time. In
+this way, HLLs and libraries and applications can add new data types to Parrot
+at the C code level, which helps to ensure speed and efficiency. PMCs loaded
+this way are called X<dynamic PMCs;dynpmcs> Dynamic PMCs or I<dynpmcs>.
+
+=head2 PIR Classes
+
+It's worth a quick diversion here to talk about the difference between a pure
+PIR class object, and a PMC. Even though classes written in PIR can inherit from
+an existing PMC type, they aren't all their own type of PMC. In fact, classes
+written in PIR are all of the Object PMC type. In order to add a new fundamental
+PMC type to Parrot, it needs to be written in C N<well, a superset of C anyway>
+and it needs to be compiled using the X<PMC compiler> PMC compiler.
+
+=head2 Writing PMCs
+
+In the strictest sense, PMCs are written in C and are compiled by your local
+C compiler into machine code for linking with libparrot or the parrot
+executable. However, Parrot's build process makes use of a special PMC compiler
+program that converts PMCs defined in a special C-like script to ordinary
+C code. The PMC compiler adds all the necessary boiler plate code and installs
+the PMC type into Parrot for use. The PMC script is like a macro superset
+N<although the functionality is a little bit more involved then is available
+in the normal C preprocessor> over the C language. All valid C is valid in
+PMC scripts, but there are also a few additions that help to make common tasks
+a little easier.
+
+The PMC script was born of conflicting necessities. The internals of Parrot
+are all written according to the ISO C89 standard for maximum portability.
+However, PIR and languages that are built on top of Parrot are typically
+object-oriented (or have some OO capabilities). PMCs are like classes,
+they have data and methods, and they can inherit from parent PMCs.
+
+C is low-level and portable, which is desirable. But Parrot needed some
+support for OO features that C doesn't have, and the C preprocessor
+can't support directly. To support the necessary features, and to make
+the task of writing PMCs just a little bit easier, the Parrot developers
+created a PMC compiler program that takes a special PMC script and converts
+it into standard ISO C89.
+
+=head3 PMC Files
+
+PMC files have a C<.pmc> file extension. They're written in a C-like
+language with a few additions to help with creating PMCs. PMC files do
+not natively allow POD documentation, so all such documentation must be
+enclosed in C</* */> comments. All PMC files that ship with Parrot
+include significant file-level and function-level documentation to help
+explain how the PMCs operate.
+
+=head3 C<pmclass> Definitions
+
+A PMC file can contain a single PMC class definition and any other helper
+functions or data structure definitions that are needed to support the
+PMC. To define a PMC class in the PMC file, you use the C<pmclass>
+statement. Everything outside the C<pmclass> definition will be ignored by
+the PMC compiler and passed through verbatim into the generated C<.c> file.
+Inside the C<pmclass> definition are going to be all the VTABLE and METHOD
+declarations for the PMC.
+
+A standard definition can contain a number of parts. Here's a pseudo-grammar
+for them:
+
+ pmclass CLASSNAME [extends PARENT]? [provides INTERFACE] [FLAGS]* {
+ /* Attributes defined here */
+
+ /* VTABLE and METHODs defined here. */
+
+ }
+
+The C<extends> keyword is optional, but allows us to specify that this
+PMC class is a subtype of the given type. If we have an C<extends>
+in the definition, we can use the C<SUPER> keyword throughout the PMC
+file to refer to the parent type.
+
+The C<FLAGS> are a series of flags that can be specified to determine
+how the PMC behaves and how it's constructed internally. The C<singleton>
+flag means that there can only be one instantiated
+object of this class. The C<is_ro> and C<has_ro> flags indicate that the
+PMC class is read-only or that it contains read-only data, respectively.
+The C<is_shared> flag indicates that the PMC is intended to be shared
+between multiple interpreters, and therefore special synchronization
+logic should be applied. The C<abstract> flag indicates that the PMC
+class cannot be instantiated directly, but can be inherited from by a
+non-abstract PMC class.
+
+The C<provides> keyword is used to show that the PMC provides certain
+standard interfaces. For instance, you can specify C<provides array>
+and then Parrot will enable us to write things like C<$P0[2]> in PIR
+code to access the PMC using integer indices. C<provides hash> means
+that we can use string and PMC keys to access values in the PMC. These
+C<provides> each correspond to a series of VTABLE interfaces that the
+PMC must provide, or must inherit. Without the necessary VTABLE
+interfaces available, Parrot may try to perform illegal operations and
+things will go badly. We'll talk about all the available C<provides>
+interfaces and the VTABLE interfaces that they must define.
+
+=head3 Attributes
+
+PMCs can be given a custom set of data field attributes using the C<ATTR>
+keyword. ATTR allows the PMC to be extended to contain custom data
+structures that are automatically managed by Parrot's memory subsystem.
+Here's an example:
+
+ pmclass Foo {
+ ATTR INTVAL bar;
+ ATTR PMC baz;
+
+ ...
+ }
+
+The attributes are stored in a custom data structure that can be accessed
+using a macro with the same name as the PMC, but all upper-case:
+
+ Parrot_Foo_Attributes * attrs = PARROT_FOO(SELF);
+ attrs->bar = 7; /* it's an INTVAL */
+ attrs->baz = pmc_new( ... ) /* it's a PMC */
+
+Notice how the type name of the attributes structure is C<Parrot_>,
+followed by the name of the PMC with the same capitalization as is used
+in the C<pmclass> definition, followed by C<_Attributes>. The macro to
+return this structure is C<PARROT_> followed by the name of the PMC in
+all caps.
+
+=head3 C<INTERP>, C<SUPER> and C<SELF>
+
+The PMC compiler enables us to use a few pre-defined variable names
+throughout the file to make things easier. The C<INTERP> keyword always
+contains a reference to the current interpreter structure. This keyword is
+included by default in all VTABLE interfaces and all PMC methods. It is not
+automatically included in any extra helper functions that you define in
+the PMC file.
+
+Here's an example of a VTABLE interface function:
+
+ VTABLE Foo(INVAR PMC, INVAR INTVAL)
+ {
+ ...
+ }
+
+The PMC compiler will convert this to the following C function definition:
+
+ void Foo(PARROT_INTERP, PMC *self, PMC *arg_1, INTVAL arg_2)
+ {
+ ...
+ }
+
+The C<interp> and C<self> variables are provided in all VTABLE interfaces,
+even though you don't have to define them explicitly in the PMC file.
+
+If the C<pmclass> definition uses the C<extends> keyword, a reference to
+a member of the parent class is also contained in the C<SUPER> variable.
+The C<SUPER()> function calls the VTABLE interface from the parent class.
+
+ VTABLE destroy()
+ {
+ SUPER(); /* Call the parent PMC's VTABLE */
+ }
+
+The PMC compiler also allows the use of "method syntax" for the C<SELF> and
+C<SUPER> variables:
+
+ SUPER.clone() /* Call the clone VTABLE interface on SUPER */
+ SELF.destroy() /* Call the destroy VTABLE interface on SELF */
+
+Or, you can call the VTABLE interfaces more directly:
+
+ VTABLE_clone(INTERP, SUPER)
+ VTABLE_destroy(INTERP, SELF)
+
+=head3 PMC Compiler
+
+The PMC compiler is a small program written in Perl 5 that's part of the
+normal Parrot build process. It converts all C<.pmc> files to C<.c> files
+for final compilation. The long-term goal for Parrot is to not be dependent
+on Perl 5 for configuration and building, but for now Perl 5 is required
+when building Parrot.
+
+=head2 VTABLE Function Definitions
+
+=head3 VTABLE Functions Parameters
+
+VTABLE functions are defined just like ordinary C functions, almost. Here's
+a normal definition for a VTABLE method:
+
+ VTABLE VTABLENAME (PARAMETERS) {
+ /* ordinary C here, almost */
+ }
+
+You can't just name your VTABLE functions anything you want. There is a
+predefined list of VTABLE function names, and you must name it exactly
+the same as the one you are trying to implement. The PARAMETERS list
+is pretty particular as well: Each VTABLE function type has a specific
+parameter list that must be implemented exactly or else the compiler
+will throw a warning.
+
+=head2 Methods
+
+VTABLES are standard, but they're rigid. They need to have the exact name
+that Parrot expects, and they need to have the exact function signature
+that Parrot expects too. VTABLES are responsible for the low-level basic
+access operations that all data types need to implement. However, to get
+more out of your PMCs, we need a more flexible want to interact with them.
+
+Enter methods, which are ways to extend the functionality of your PMC
+in ways that the PMC needs. Methods allow the developer to add all sorts
+of arbitrary functionality to a PMC that the VTABLE functions themselves
+cannot define.
+
+=head2 Dynpmcs
+
+=head3 Loading dynpmcs
+
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
259 2.0.0/book/draft/ch08_dynops.pod
@@ -0,0 +1,259 @@
+=pod
+
+=head1 Dynamic Opcodes
+
+Z<CHP-12>
+
+The smallest executable component is not the compilation unit or even the
+subroutine, but is actually the I<opcode>. Opcodes in Parrot, like opcodes in
+other machines (both virtual and physical), are individual instructions that
+implement low-level operations in the machine. In the world of
+microprocessors, the word "opcode" typically refers to the numeric identifier
+for each instructions. The human-readable word used in the associated assembly
+language is called the "mnemonic". An assembler, among other tasks, is
+responsible for converting mnemonics into opcodes for execution. In Parrot,
+instead of referring to an instruction by different names depending on what
+form it's in, we just call them all "opcodes".
+
+=head2 Opcodes
+
+Opcodes are the smallest logical execution element in Parrot. An
+individual opcode corresponds, in an abstract kind of way, with a single
+machine code instruction for a particular hardware processor
+architecture. Parrot is a pretty high-level virtual machine, and even though
+its opcodes represent the smallest bits of executable code in Parrot, they
+are hardly small or low-level by themselves. In fact, some Parrot opcodes
+implement some complex operations and algorithms. Other opcodes are more
+traditional, performing basic arithmetic and data manipulating operations.
+
+Parrot comes with about 1,200 opcodes total in a basic install. It also has a
+facility for dynamically loading additional opcode libraries, called
+C<dynops>, as needed.
+
+=head3 Opcode naming
+
+To the PIR and PASM programmers, opcodes appear to be polymorphic. That
+is, some opcodes appear to have multiple allowable argument formats. This is
+just an illusion, however. Parrot opcodes are not polymorphic, although
+certain features enable them to appear that way to the PIR programmer.
+Different argument list formats are detected during parsing and mapped to
+separate, unique opcode names.
+
+During the Parrot build process, opcode definitions called "ops files" are
+translated into C code prior to compilation. This translation process renames
+all ops to use unique names depending on their argument lists. An op "foo"
+that takes two PMCs and returns an integer would be renamed to C<foo_i_p_p>.
+Another op named "foo" that takes one floating point number and returns a
+string would be renamed to C<foo_s_n>. So, when we call the opcode "foo" from
+our PIR program, the PIR compiler will look at the list of arguments and
+call the appropriate opcode to handle it.
+
+=head2 Writing Opcodes
+
+Writing Opcodes, like writing PMCs, is done in a C-like language which is
+later compiled into C code by the X<opcode compiler> opcode compiler. The
+opcode script represents a thin overlay on top of ordinary C code: All
+valid C code is valid opcode script. There are a few neat additions that
+make writing opcodes easier. The C<INTERP> keyword, for instance, contains
+a reference to the current interpreter structure. C<INTERP> is always
+available when writing opcodes, even though it isn't defined anywhere.
+Opcodes are all defined with the C<op> keyword.
+
+Opcodes are written in files with the C<.ops> extension. The core
+operation files are stored in the C<src/ops/> directory.
+
+=head3 Opcode Parameters
+
+Each opcode can take any fixed number of input and output arguments. These
+arguments can be any of the four primary data types--INTVALs, PMCs, NUMBERS
+and STRINGs--but can also be one of several other types of values including
+LABELs, KEYs and INTKEYs.
+
+Each parameter can be an input, an output or both, using the C<in>, C<out>,
+and C<inout> keywords respectively. Here is an example:
+
+ op Foo (out INT, in NUM)
+
+This opcode could be called like this:
+
+ $I0 = Foo $N0 # in PIR syntax
+ Foo I0, N0 # in PASM syntax
+
+When Parrot parses through the file and sees the C<Foo> operation, it
+converts it to the real name C<Foo_i_n>. The real name of an opcode
+is its name followed by an underscore-separated ordered list of
+the parameters to that opcode. This is how Parrot appears to use
+polymorphism: It translates the overloaded opcode common names into
+longer unique names depending on the parameter list of that opcode. Here
+is a list of some of the variants of the C<add> opcode:
+
+ add_i_i # $I0 += $I1
+ add_n_n # $N0 += $N1
+ add_p_p # $P0 += $P1
+ add_i_i_i # $I0 = $I1 + $I2
+ add_p_p_i # $P0 = $P1 + $I0
+ add_p_p_n # $P0 = $P1 + $N0
+
+This isn't a complete list, but you should get the picture. Each different
+combination of parameters translates to a different unique operation, and
+each operation is remarkably simple to implement. In some cases, Parrot
+can even use its multi-method dispatch system to call opcodes which are
+heavily overloaded, or for which there is no exact fit but the parameters
+could be coerced into different types to complete the operation. For
+instance, attempting to add a STRING to a PMC might coerce the string into
+a numerical PMC type first, and then dispatch to the C<add_p_p_n> opcode.
+This is just an example, and the exact mechanisms may change as more opcodes
+are added or old ones are deleted.
+
+Parameters can be one of the following types:
+
+=over 4
+
+=item * INT
+
+A normal integer type, such as one of the I registers
+
+=item * NUM
+
+A floating point number, like is used in the N registers
+
+=item * STR
+
+A string, such as in a S register
+
+=item * PMC
+
+A PMC value, like a P register
+
+=item * KEY
+
+A key value. Something like C<[5 ; "Foo" ; 6 ; "Bar"]>. These are the same
+as indexes that we use in PMC aggregates.
+
+=item * INTKEY
+
+A basic key value that uses only integer values C<[1 ; 2 ; 3 ]>.
+
+=item * LABEL
+
+A label value, which represents a named statement in PIR or PASM code.
+
+=back
+
+In addition to these types, you need to specify the direction that data is
+moving through that parameter:
+
+=over 4
+
+=item * in
+
+The parameter is an input, and should be initialized before calling the op.
+
+=item * out
+
+The parameter is an output
+
+=item * inout
+
+The parameter is an input and an output. It should be initialized before
+calling the op, and it's value will change after the op executes.
+
+=item * invar
+
+The parameter is a reference type like a String or PMC, and it's internals
+might change in the call.
+
+=back
+
+=head3 Opcode Control Flow
+
+Some opcodes have the ability to alter control flow of the program they
+are in. There are a number of control behaviors that can be implemented,
+such as an unconditional jump in the C<goto> opcode, or a subroutine
+call in the C<call> code, or the conditional behavior implemented by C<if>.
+
+At the end of each opcode you can call a C<goto> operation to jump to the
+next opcode to execute. If no C<goto> is performed, control flow will
+continue like normal to the next operation in the program. In this way,
+opcodes can easily manipulate control flow. Opcode script provides a
+number of keywords to alter control flow:
+
+=over 4
+
+=item * NEXT()
+
+The keyword C<NEXT> contains the address of the next opcode in memory. At the
+end of a normal op you don't need to call C<goto NEXT()> because moving to the
+next opcode in the program is the default behavior of Parrot N<You can do
+this if you really want to, but it really wouldn't help you any>. The C<NEXT>
+keyword is frequently used in places like the C<invoke> opcode to create a
+continuation to the next opcode to return to after the subroutine returns.
+
+=item * ADDRESS()
+
+Jumps execution to the given address.
+
+ ADDRESS(x);
+
+Here, C<x> should be an C<opcode_t *> value of the opcode to jump to.
+
+=item * OFFSET()
+
+Jumps to the address given as an offset from the current address.
+
+ OFFSET(x)
+
+Here, C<x> is an offset in C<size_t> units that represents how far forward
+(positive) or how far backwards (negative) to jump to.
+
+=back
+
+=head2 The Opcode Compiler
+
+As we've seen in our discussions above, ops have a number of transformations
+to go through before they can be become C code and compiled into Parrot.
+The various special variables like C<$1>, C<INTERP> and C<ADDRESS> need to be
+converted to normal variable values. Also, each runcore requires the ops be
+compiled into various formats: The slow and fast cores need the ops to be
+compiled into individual subroutines. The switch core needs all the ops to be
+compiled into a single function using a large C<switch> statement. The
+computed goto cores require the ops be compiled into a large function with a
+large array of label addresses.
+
+Parrot's opcode compiler is a tool that's tasked with taking raw opcode files
+with a C<.ops> extension and converting them into several different formats,
+all of which need to be syntactically correct C code for compilation.
+
+=head2 Dynops
+
+Parrot has about 1200 built-in opcodes. These represent operations which are
+sufficiently simple and fundamental, but at the same time are very common.
+However, these do not represent all the possible operations that some
+programmers are going to want to use. Of course, not all of those 1200 ops
+are unique, many of them are overloaded variants of one another. As an example
+there are about 36 variants of the C<set> opcode, to account for all the
+different types of values you may want to set to all the various kinds of
+registers. The number of unique operations therefore is much smaller then 1200.
+
+This is where I<dynops> come in. Dynops are dynamically-loadable libraries of
+ops that can be written and compiled separately from Parrot and loaded in at
+runtime. dynops, along with dynpmcs and runtime libraries are some of the
+primary ways that Parrot can be extended.
+
+Parrot ships with a small number of example dynops libraries in the file
+L<src/dynoplibs/>. These are small libraries of mostly nonsensical but
+demonstrative opcodes that can be used as an example to follow.
+
+Dynops can be written in a C<.ops> file like the normal built-in ops are.
+The ops file should use C<#include "parrot/extend.h"> in addition to any
+other libraries the ops need. They can be compiled into C using the opcode
+compiler, then compiled into a shared library using a normal C compiler. Once
+compiled, the dynops can be loaded into Parrot using the .loadlib directive.
+
+=cut
+
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
2,923 2.0.0/book/draft/ch10_opcode_reference.pod
2,923 additions, 0 deletions not shown because the diff is too large. Please use a local Git client to view these changes.
View
227 2.0.0/book/draft/ch11_directive_reference.pod
@@ -0,0 +1,227 @@
+=pod
+
+=head1 Directive Reference
+
+Z<CHP-13-SECT-2>
+
+X<PIR (Parrot intermediate representation);quick reference;directives>
+This is a summary of PIR directives. Directives are preprocessed by the
+Parrot interpreter. Since PIR and PASM run on the same interpreter, many
+of the directives listed here are also valid in PASM code.
+
+
+=head3 .arg
+
+X<.arg directive>
+
+ .arg R<VAL>
+
+pass a value to a subroutine according to PCC.
+
+=head3 .const
+
+X<.const directive>
+
+ .const R<TYPE>R<NAME> = R<VALUE>
+
+Define a named constant.
+
+=head3 .macro_const
+
+X<.macro_const directive>
+
+ .macro_const R<NAME>R<VALUE>
+
+Define a named macro that expands to a given value. Macros are called
+as directives, i.e. .R<NAME> (PASM code only).
+
+=head3 .emit
+
+X<.emit directive>
+
+ .emit
+
+Define a block of PASM code. Always paired with C<.eom>.
+
+=head3 .end
+
+X<.end directive>
+
+ .end
+
+End a subroutine. Always paired with C<.sub>.
+
+=head3 .endm
+
+X<.endm directive>
+
+ .endm
+
+End a macro definition. Always paired with C<.macro>.
+
+=head3 .eom
+
+X<.eom directive>
+
+ .eom
+
+End a block of PASM code. Always paired with C<.emit>.
+
+=head3 .flatten_arg
+
+X<.flatten_arg directive>
+
+ .flatten_arg R<PArray>
+
+Flatten the passed array PMC and provide args for PCC calls.
+
+=head3 .globalconst
+
+X<.globalconst directive>
+
+ .globalconst R<TYPE>R<NAME> = R<VALUE>
+
+Define a named, file visible constant.
+
+=head3 .include
+
+X<.include directive>
+
+ .include " R<FILENAME> "
+
+Include the contents of an external file by inserting it in place.
+
+=head3 .invocant
+
+X<.invocant directive>
+
+ .invocant R<OBJ>
+
+Set the invocant for a method call.
+
+=head3 .local
+
+X<.local directive>
+
+ .local R<TYPE>R<NAME>
+
+Define a local named variable.
+
+=head3 .macro
+
+X<.macro directive>
+
+ .macro R<NAME> (R<PARAMS>)
+
+Define a named macro with a list of parameters. The macro is called as
+.R<NAME>(R<arg1>,R<arg2>,...). Always paired with C<.endm>.
+
+=head3 .meth_call
+
+X<.meth_call directive>
+
+ .meth_call R<SUB>
+ .meth_call R<SUB>, R<RETCONT>
+
+Create a method call.
+
+=head3 .namespace
+
+X<.namespace directive>
+
+ .namespace R< [ "namespace" ] >
+
+Define a namespace.
+
+=head3 .nci_call
+
+X<.nci_call directive>
+
+ .nci_call R<SUB>
+
+Create an NCI call.
+
+=head3 .param
+
+X<.param directive>
+
+ .param R<DEST>
+ .param R<TYPE>R<NAME>
+
+Define a subroutine parameter.
+
+=head3 .begin_call
+
+X<.begin_call directive>
+
+Start a call sequence. Always paired with C<.end_call>
+
+=head3 .begin_return
+
+X<.begin_return directive>
+
+Start a return sequence. Always paired with C<.end_return>
+
+=head3 .begin_yield
+
+X<.begin_yield directive>
+
+Start a return of a coroutine sequence. Always paired with C<.end_yield>
+
+=head3 .call
+
+X<.call directive>
+
+ .call R<SUB>
+ .call R<SUB>, R<RETCONT>
+
+Create a subroutine call.
+
+=head3 .pcc_sub
+
+X<.pcc_sub directive>
+
+ .pcc_sub R<_LABEL>
+
+Create a symbol entry for subroutine at the _LABEL. This directive is
+for PASM code only.
+
+=head3 .result
+
+X<.result directive>
+
+ .result R<DEST>
+
+Get a return value according to PCC.
+
+=head3 .return
+
+X<.return directive>
+
+ .return R<VAL>
+
+Return a value to the calling subroutine according to PCC.
+
+=head3 .sub
+
+X<.sub directive>
+
+ .sub R<NAME>
+
+Define a subroutine. Always paired with C<.end>. Names begin
+with "C<_>" by convention.
+
+=head3 .sym
+
+X<.sym directive>
+
+ .sym R<TYPE> R<NAME>
+
+Same as C<.local>.
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
299 2.0.0/book/draft/ch12_operator_reference.pod
@@ -0,0 +1,299 @@
+=pod
+
+=head1 PIR Operator Reference
+
+Z<CHP-13-SECT-3>
+
+X<PIR (Parrot intermediate representation);quick reference;instructions>
+This section is a quick reference to PIR instructions. For more details
+and the latest changes, see F<imcc/docs/syntax.pod> or dive into the
+source code in F<imcc/imcc.l> and F<imcc/imcc.y>.
+
+=head3 =
+
+X<= (equal sign);= (assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL>
+
+Assign a value to a particular register, temporary register, or named
+variable.
+
+=head3 +, +=
+
+X<+ (plus sign);+ (addition);instruction (PIR)>
+X<+ (plus sign);+= (addition assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL> + R<VAL>
+ R<DEST> += R<VAL>
+
+Add two numbers or PMCs.
+
+=head3 -, -=
+
+X<- (hyphen);- (subtraction);instruction (PIR)>
+X<- (hyphen);-= (subtraction assignment);instruction (PIR)>
+X<- (hyphen);- (negation);instruction (PIR)>
+
+ R<DEST> = R<VAL1> - R<VAL2>
+ R<DEST> -= R<VAL1>
+ R<DEST> = - R<VAL>
+
+Subtract R<VAL1> from R<VAL2>. The unary "C<->" negates a number.
+
+=head3 *, *=
+
+X<* (asterisk);* (multiplication);instruction (PIR)>
+X<* (asterisk);*= (multiplication assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL> * R<VAL>
+ R<DEST> *= R<VAL>
+
+Multiply two numbers or PMCs.
+
+=head3 /, /=
+
+X</ (slash);/ (division);instruction (PIR)>
+X</ (slash);/= (division assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL1> / R<VAL2>
+ R<DEST> /= R<VAL1>
+
+Divide R<VAL1> by R<VAL2>.
+
+=head3 **
+
+X<* (asterisk);** (exponentiation);instruction (PIR)>
+
+ R<DEST> = R<VAL1> ** R<VAL2>
+
+Raise R<VAL1> to the power of R<VAL2>.
+
+=head3 %, %=
+
+X<% (percent sign);% (modulus);instruction (PIR)>
+X<% (percent sign);%= (modulus assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL1> % R<VAL2>
+ R<DEST> %= R<VAL1>
+
+Divide R<VAL1> by R<VAL2> and return the (C<mod>) remainder.
+
+=head3 ., .=
+
+X<. (dot);. (concatenation) instruction (PIR)>
+X<. (dot);.= (concatenation assignment) instruction (PIR)>
+
+ R<DEST> = R<VAL> . R<VAL>
+ R<DEST> .= R<VAL>
+
+Concatenate two strings. The concat operator must be surrounded by
+whitespace.
+
+=head3 E<lt>
+
+X<E<lt> (left angle bracket);E<lt> (less than);instruction (PIR)>
+
+ if R<VAL1> E<lt> R<VAL2> goto R<LABEL>
+
+Conditionally branch to a label if R<VAL1> is less than R<VAL2>.
+
+=head3 E<lt>=
+
+X<E<lt> (left angle bracket);E<lt>= (less than or equal);instruction (PIR)>
+
+ if R<VAL1> E<lt>= R<VAL2> goto R<LABEL>
+
+Conditionally branch to a label if R<VAL1> is less than or equal to
+R<VAL2>.
+
+=head3 E<gt>
+
+X<E<gt> (right angle bracket);E<gt> (greater than);instruction (PIR)>
+
+ if R<VAL1> E<gt> R<VAL2> goto R<LABEL>
+
+Conditionally branch to a label if R<VAL1> is greater than R<VAL2>.
+
+=head3 E<gt>=
+
+X<E<gt> (right angle bracket);E<gt>= (greater than or equal);instruction (PIR)>
+
+ if R<VAL1> E<gt>= R<VAL2> goto R<LABEL>
+
+Conditionally branch to a label if R<VAL1> is greater than or equal to
+R<VAL2>.
+
+=head3 ==
+
+X<= (equal sign);== (equality);instruction (PIR)>
+
+ if R<VAL1> == R<VAL2> goto R<LABEL>
+
+Conditionally branch to a label if R<VAL1> is equal to R<VAL2>.
+
+=head3 !=
+
+X<! (bang);!= (not equal);instruction (PIR)>
+
+ if R<VAL1> != R<VAL2> goto R<LABEL>
+
+Conditionally branch to a label if R<VAL1> is not equal to R<VAL2>.
+
+=head3 &&
+
+X<& (ampersand);&& (logical AND);instruction (PIR)>
+
+ R<DEST> = R<VAL1> && R<VAL2>
+
+Logical AND. Return R<VAL1> if it's false, otherwise return R<VAL2>.
+
+=head3 ||
+
+X<| (pipe);|| (logical OR);instruction (PIR)>
+
+ R<DEST> = R<VAL1> || R<VAL2>
+
+Logical OR. Return R<VAL1> if it's true, otherwise return R<VAL2>.
+
+=head3 ~~
+
+X<~ (tilde);~~ (logical XOR) instruction (PIR)>
+
+ R<DEST> = R<VAL1> ~~ R<VAL2>
+
+Logical XOR. If R<VAL1> is true and R<VAL2> is false, return R<VAL1>.
+If R<VAL1> is false and R<VAL2> is true, return R<VAL2>. Otherwise,
+return a false value.
+
+=head3 !
+
+X<! (bang);! (not);instruction (PIR)>
+
+ R<DEST> = ! R<VAL>
+
+Logical NOT. Return a true value if R<VAL> is false.
+
+=head3 &, &=
+
+X<& (ampersand);& (bitwise AND) instruction (PIR)>
+X<& (ampersand);&= (bitwise AND assignment) instruction (PIR)>
+
+ R<DEST> = R<VAL> & R<VAL>
+ R<DEST> &= R<VAL>
+
+Bitwise AND on two values.
+
+=head3 |, |=
+
+X<| (pipe);| (bitwise AND) instruction (PIR)>
+X<| (pipe);|= (bitwise AND assignment) instruction (PIR)>
+
+ R<DEST> = R<VAL> | R<VAL>
+ R<DEST> |= R<VAL>
+
+Bitwise OR on two values.
+
+=head3 ~, ~=
+
+X<~ (tilde);~ (bitwise XOR) instruction (PIR)>
+X<~ (tilde);~= (bitwise XOR assignment) instruction (PIR)>
+
+ R<DEST> = R<VAL> ~ R<VAL>
+ R<DEST> ~= R<VAL>
+ R<DEST> = ~ R<VAL>
+
+Bitwise XOR on two values. The unary form is a bitwise NOT on a value.
+
+=head3 E<lt>E<lt>, E<lt>E<lt>=
+
+X<E<lt> (left angle bracket);E<lt>E<lt> (bitwise left shift);instruction (PIR)>
+X<E<lt> (left angle bracket);E<lt>E<lt>= (bitwise left shift assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL1> E<lt>E<lt> R<VAL2>
+ R<DEST> E<lt>E<lt>= R<VAL2>
+
+Bitwise shift R<VAL1> left by R<VAL2> number of bits.
+
+=head3 E<gt>E<gt>, E<gt>E<gt>=
+
+X<E<gt> (right angle bracket);E<gt>E<gt> (bitwise right shift);instruction (PIR)>
+X<E<gt> (right angle bracket);E<gt>E<gt>= (bitwise right shift assignment);instruction (PIR)>
+
+ R<DEST> = R<VAL1> E<gt>E<gt> R<VAL2>
+ R<DEST> E<gt>E<gt>= R<VAL2>
+
+Bitwise shift R<VAL1> right by R<VAL2> number of bits.
+
+=head3 E<gt>E<gt>E<gt>, E<gt>E<gt>E<gt>=
+
+X<E<gt> (right angle bracket);E<gt>E<gt>E<gt> (logical right shift) instruction (PIR)>
+X<E<gt> (right angle bracket);E<gt>E<gt>E<gt>= (logical right shift assignment) instruction (PIR)>
+
+ R<DEST> = R<VAL1> E<gt>E<gt>E<gt> R<VAL2>
+ R<DEST> E<gt>E<gt>E<gt>= R<VAL2>
+
+Logically shift R<VAL1> right by R<VAL2> number of bits.
+
+=head3 [ ]
+
+X<[] (brackets);indexed access to PMC (PIR)>
+
+ R<DEST> = R<PMC> [ R<KEY> ]
+ R<PMC> [ R<KEY> ] = R<VAL>
+
+Indexed access to a PMC and indexed assignment to a PMC.
+
+ DEST = STRING [ OFFSET ]
+ STRING [ OFFSET ] = VAL
+
+Access a one-character substring on a string, starting at a particular
+offset, or assign to that substring.
+
+=head3 call
+
+X<call instruction (PIR)>
+
+ call R<NAME>
+
+Call the named subroutine (a C<.sub> label).
+
+=head3 global
+
+X<global instruction (PIR)>
+
+ R<DEST> = global R<NAME>
+ global R<NAME> = R<VAL>
+
+Access a global variable for read or write.
+
+=head3 goto
+
+X<goto command (PIR)>
+
+ goto R<NAME>
+
+Jump to the named identifier (label or subroutine name).
+
+=head3 if
+
+X<if (conditional);instruction (PIR)>
+
+ if R<EXPR> goto R<NAME>
+
+If the value or expression evaluates as true, jump to the named
+identifier.
+
+=head3 unless
+
+X<unless (conditional);instruction (PIR)>
+
+ unless R<VAL> goto R<NAME>
+
+Unless the value evaluates as true, jump to the named identifier.
+
+=cut
+
+# Local variables:
+# c-file-style: "parrot"
+# End:
+# vim: expandtab shiftwidth=4:
View
292 2.0.0/book/draft/chXX_hlls.pod
@@ -0,0 +1,292 @@
+=pod
+
+=head1 HLLs and Interoperation
+
+Z<CHP-10>
+
+=head2 Parrot HLL Environment
+
+In the earliest days Parrot was designed to be the single-purpose backend
+for the Perl 6 language. It quickly blossomed beyond that, and now has a
+much grander purpose: to host all dynamic languages, and to host them
+together on a single platform. If we look back through the history of
+dynamic programming languages, they've had a more difficult time
+interoperating with each other then compiled languages have because
+compiled languages operate at the same machine-code level and typically
+can make use of the same application binary interface (ABI). With the
+right compiler settings, programs written in Visual Basic can interoperate
+with programs written in C N<On some systems anyway>, which can call
+functions written in C++, in Ada, Fortran, Pascal and so on. To try to mix
+two common dynamic languages, like Perl and Python, or Ruby and PHP, you
+would need to write some kind of custom "glue" function to try to include
+an interpreter object from one language as a library for another language,
+and then write code to try and get the parser for one to interact nicely
+with the parser for the other. It's a nightmare, frankly, and you don't
+see it happen too often.
+
+In Parrot, the situation is different because high level languages (HLL)
+are almost all written with the PCT tools, and are compiled to the same
+PIR and PBC code. Once compiled into PBC, a library written in any HLL
+language can be loaded and called by any other HLL N<Well, any HLL which
+supports loading libraries>. A language can have a syntax to include
+code snippets from other languages inline in the same file. We can write
+a binding for a popular library such as opengl or xlib once, and include
+that library into any language that needs it. Compare this to the current
+situation where a library like Gtk2 needs to have bindings for every
+language that wants to use it. In short, Parrot should make interoperation
+easier for everybody.
+
+This chapter is going to talk about HLLs, the way they operate, and the
+way they interoperate on Parrot.
+
+=head2 HLLs on Parrot
+
+=head2 Working with HLLs
+
+=head3 Fakecutables
+
+It's possible to turn compilers created with PCT into stand-alone
+executables that run without the Parrot executable. To do this, the
+compiler bytecode is linked together with a small driver program in
+C and the Parrot library, C<libparrot> X<libparrot>. These programs
+have been given a special name by the Parrot development community:
+I<fakecutables> X<fakecutables>. They're called fake because the PBC
+is not converted to native machine code like in a normal binary
+executable file, but instead is left in original PBC format.
+
+=head3 Compiler Objects
+
+The C<compreg> opcode has two forms that are used with HLL compilers. The
+first form stores an object as a compiler object to be retrieved later, and
+the second form retrieves a stored compiler object for a given language.
+The exact type of compiler object stored with C<compreg> can vary for each
+different language implementation, although most of the languages using PCT
+will have a common form. If a compiler object is in register C<$P0>, it can
+be stored using the following C<compreg> syntax:
+
+=begin PIR_FRAGMENT
+
+ compreg 'MyCompiler', $P0
+
+=end PIR_FRAGMENT
+
+There are two built-in compiler objects: One for PIR and one for PASM. These
+two don't need to be stored first, they can simply be retrieved and used.
+The PIR and PASM compiler objects are Sub PMCs that take a single string
+argument and return an array PMC containing a list of all the compiled
+subroutines from the string. Other compiler objects might be different
+entirely, and may need to be used in different ways. A common convention is
+for a compiler to be an object with a C<compile> method. This is done with
+PCT-based compilers and for languages who use a stateful compiler.
+
+Compiler objects allow programs in Parrot to compile arbitrary code strings
+at runtime and execute them. This ability, to dynamically compile
+code that is represented in a string variable at runtime, is of fundamental
+importance to many modern dynamic languages. Here's an example using
+the PIR compiler:
+
+=begin PIR_FRAGMENT
+
+ .local string code
+ code = "..."
+ $P0 = compreg 'PIR' # Get the compiler object
+ $P1 = $P0(code) # Compile the string variable "code"
+
+=end PIR_FRAGMENT
+
+The returned value from invoking the compiler object is an array of PMCs
+that contains the various executable subroutines from the compiled source.
+Here's a more verbose example of this:
+
+=begin PIR_FRAGMENT
+
+ $P0 = compreg 'PIR'
+ $S0 = <<"END_OF_CODE"
+
+ .sub 'hello'
+ say 'hello world!'
+ .end
+
+ .sub 'goodbye'
+ say 'goodbye world!'