Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

'Updated 'parrot.github.com'

  • Loading branch information...
commit a175424515bd8c28d15834b0934c32a760f73269 1 parent d907218
@ayardley ayardley authored
Showing with 33,251 additions and 0 deletions.
  1. +70 −0 Makefile
  2. +230 −0 README.pod
  3. +24 −0 binaries/README.pod
  4. +54 −0 binaries/ops2c.pod
  5. +80 −0 binaries/parrot-nqp.pod
  6. +98 −0 binaries/parrot-prove.pod
  7. +417 −0 binaries/parrot.pod
  8. +36 −0 binaries/parrot_config.pod
  9. +73 −0 binaries/parrot_nci_thunk_gen.pod
  10. +95 −0 binaries/parrotbug.pod
  11. +67 −0 binaries/pbc_to_exe.pod
  12. +147 −0 binaries/plumage.pod
  13. +40 −0 binaries/winxed.pod
  14. +62 −0 book/draft/README.pod
  15. +314 −0 book/draft/appa_glossary.pod
  16. +138 −0 book/draft/appb_patch_submission.pod
  17. +306 −0 book/draft/appc_command_line_options.pod
  18. +93 −0 book/draft/appd_build_options.pod
  19. +72 −0 book/draft/appe_source_code.pod
  20. +215 −0 book/draft/ch01_introduction.pod
  21. +182 −0 book/draft/ch02_getting_started.pod
  22. +234 −0 book/draft/ch07_dynpmcs.pod
  23. +259 −0 book/draft/ch08_dynops.pod
  24. +2,915 −0 book/draft/ch10_opcode_reference.pod
  25. +210 −0 book/draft/ch11_directive_reference.pod
  26. +299 −0 book/draft/ch12_operator_reference.pod
  27. +293 −0 book/draft/chXX_hlls.pod
  28. +107 −0 book/draft/chXX_library.pod
  29. +128 −0 book/draft/chXX_testing_and_debugging.pod
  30. +215 −0 book/pct/ch01_introduction.pod
  31. +182 −0 book/pct/ch02_getting_started.pod
  32. +333 −0 book/pct/ch03_compiler_tools.pod
  33. +1,567 −0 book/pct/ch04_pge.pod
  34. +221 −0 book/pct/ch05_nqp.pod
  35. +113 −0 book/pir/ch01_introduction.pod
  36. +78 −0 book/pir/ch02_getting_started.pod
  37. +314 −0 book/pir/ch03_basic_syntax.pod
  38. +1,834 −0 book/pir/ch04_variables.pod
  39. +343 −0 book/pir/ch05_control_structures.pod
  40. +1,300 −0 book/pir/ch06_subroutines.pod
  41. +497 −0 book/pir/ch07_objects.pod
  42. +411 −0 book/pir/ch08_io.pod
  43. +397 −0 book/pir/ch09_exceptions.pod
  44. +772 −0 compiler_faq.pod
  45. +304 −0 configuration.pod
  46. +242 −0 debug.pod
  47. +399 −0 debugger.pod
  48. +231 −0 deprecations/deprecations.pod
  49. +73 −0 deprecations/deprecations_2_6.pod
  50. +200 −0 deprecations/deprecations_2_9.pod
  51. +222 −0 deprecations/deprecations_3_0.pod
  52. +28 −0 deprecations/deprecations_3_3.pod
  53. +59 −0 deprecations/deprecations_3_6.pod
  54. +136 −0 deprecations/how_to_deprecate.pod
  55. +153 −0 dev/byteorder.pod
  56. +228 −0 dev/c_functions.pod
  57. +61 −0 dev/coverage.pod
  58. +126 −0 dev/debugging_with_msvc.pod
  59. +118 −0 dev/events.pod
  60. +40 −0 dev/headerizer.pod
  61. +316 −0 dev/infant.pod
  62. +66 −0 dev/longopt.pod
  63. +181 −0 dev/optimizer.pod
  64. +39 −0 dev/parrot_api.pod
  65. +133 −0 dev/pcc_methods.pod
  66. +102 −0 dev/pcc_state.pod
  67. +236 −0 dev/pmc_freeze.pod
  68. +239 −0 dev/pmc_obj_design_meeting_notes.pod
  69. +130 −0 dev/profiling.pod
  70. +1,619 −0 embed.pod
  71. +336 −0 embed_new.pod
  72. +42 −0 extend.pod
  73. +82 −0 faq.pod
  74. +197 −0 gettingstarted.pod
  75. +321 −0 glossary.pod
  76. +76 −0 html/DONORS.pod.html
  77. +52 −0 html/book.html
  78. +101 −0 html/developer.html
  79. +186 −0 html/docs/book/draft/appa_glossary.pod.html
  80. +136 −0 html/docs/book/draft/appb_patch_submission.pod.html
  81. +161 −0 html/docs/book/draft/appc_command_line_options.pod.html
  82. +108 −0 html/docs/book/draft/appd_build_options.pod.html
  83. +74 −0 html/docs/book/draft/appe_source_code.pod.html
  84. +254 −0 html/docs/book/draft/ch01_introduction.pod.html
  85. +158 −0 html/docs/book/draft/ch02_getting_started.pod.html
  86. +226 −0 html/docs/book/draft/ch07_dynpmcs.pod.html
  87. +248 −0 html/docs/book/draft/ch08_dynops.pod.html
  88. +3,274 −0 html/docs/book/draft/ch10_opcode_reference.pod.html
  89. +304 −0 html/docs/book/draft/ch11_directive_reference.pod.html
  90. +420 −0 html/docs/book/draft/ch12_operator_reference.pod.html
  91. +325 −0 html/docs/book/draft/chXX_hlls.pod.html
  92. +138 −0 html/docs/book/draft/chXX_library.pod.html
  93. +131 −0 html/docs/book/draft/chXX_testing_and_debugging.pod.html
  94. +254 −0 html/docs/book/pct/ch01_introduction.pod.html
  95. +158 −0 html/docs/book/pct/ch02_getting_started.pod.html
  96. +346 −0 html/docs/book/pct/ch03_compiler_tools.pod.html
  97. +645 −0 html/docs/book/pct/ch04_pge.pod.html
  98. +230 −0 html/docs/book/pct/ch05_nqp.pod.html
  99. +160 −0 html/docs/book/pir/ch01_introduction.pod.html
  100. +91 −0 html/docs/book/pir/ch02_getting_started.pod.html
  101. +220 −0 html/docs/book/pir/ch03_basic_syntax.pod.html
  102. +1,182 −0 html/docs/book/pir/ch04_variables.pod.html
  103. +306 −0 html/docs/book/pir/ch05_control_structures.pod.html
  104. +793 −0 html/docs/book/pir/ch06_subroutines.pod.html
Sorry, we could not display the entire diff because too many files (452) changed.
View
70 Makefile
@@ -0,0 +1,70 @@
+# ex: set ro:
+# DO NOT EDIT THIS FILE
+# Generated by Parrot::Configure::Compiler from config/gen/makefiles/docs.in
+
+# Copyright (C) 2001-2010, Parrot Foundation.
+
+# Setup of some commands
+PERL = /usr/bin/perl
+CHMOD = $(PERL) -MExtUtils::Command -e 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_BIN = /usr/bin/perldoc
+VERSION = 4.4.0-devel
+
+#
+# Targets
+#
+# 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:"
+ @echo ""
+ @echo "help Generate this usage statement."
+ @echo " This is the default target."
+ @echo ""
+ @echo "html Generate html documentation"
+ @echo "html-clean Remove html documentation"
+ @echo ""
+ @echo "htmlhelp: windows only, generate a .chm file."
+ @echo "htmlhelp-clean: Remove generated .chm"
+ @echo ""
+ @echo "pdf: Generate a PDF from the html docs"
+ @echo "pdf-clean: Remove generated pdf"
+ @echo ""
+ @echo " clean: Invoke all clean targets"
+ @echo ""
+
+clean: htmlhelp-clean html-clean
+
+html:
+ $(PERL) -I../lib ../tools/docs/mk_html_docs.pl --version=$(VERSION)
+html-clean:
+ $(RM_RF) html
+
+# If you are missing the command 'pdflatex' then you have first to install a
+# LaTeX distribution with it. For Windows and UNIX downloads are for example
+# available from: http://miktex.org, http://tug.org/texlive or
+# http://www.ctan.org
+pdf: ../tools/docs/filename_and_chapter.pl
+ $(MKPATH) build/modified_pod
+ $(PERL) ../tools/docs/filename_and_chapter.pl
+ cd build && pdflatex parrot-book.tex && pdflatex parrot-book.tex
+
+#pdf-release: build/parrot-book.pdf
+# cp build/parrot-book.pdf build/parrot-book-$$(date +"%Y.%m").pdf
+
+pdf-clean:
+ $(RM_RF) build
+
+htmlhelp: html
+
+htmlhelp-clean:
+
+# Local variables:
+# mode: makefile
+# End:
+# vim: ft=make:
View
230 README.pod
@@ -0,0 +1,230 @@
+# Copyright (C) 2001-2012, Parrot Foundation.
+
+=pod
+
+=head1 NAME
+
+docs/README.pod - Readme file for the 'docs/' directory.
+
+=head1 DESCRIPTION
+
+This README sets out the documents and directories in the 'docs/' top-level
+directory.[1]
+
+=head2 Documentation
+
+=over 4
+
+=item F<binaries/>
+
+The pod files for Parrot's installable executables.
+
+=item F<book/>
+
+The pod files for the "PCT Book," the "PIR Book," and a draft of the "Parrot
+Developer's Guide: PIR Book".
+
+=item F<compiler_faq.pod>
+
+A Parrot FAQ for compiler writers in PIR.[2]
+
+=item F<configuration.pod>
+
+A document on Parrot's Configuration System.
+
+=item F<debugger.pod>
+
+Documentation for C<parrot_debugger>, the Parrot debugger.
+
+=item F<debug.pod>
+
+A beginner's guide to debugging the Parrot executable.
+
+=item F<deprecations/>
+
+Documentation on Parrot's deprecation policy and documents on various Parrot
+deprecations.
+
+=item F<dev/>
+
+This subdirectory contains a number of files discussing various implementation
+decisions made during the course of the development of Parrot. The intent is
+to keep discussion of implementation-specific issues separate from the basic
+design issues discussed in the PDDs.
+
+=item F<embed_new.pod>
+
+An overview of Parrot's embedding system.
+
+=item F<embed.pod>
+
+Describes the embedding subsystem in excruciating detail.
+
+=item F<extend.pod>
+
+A (mostly empty) description of Parrot's extension system.
+
+=item F<faq.pod>
+
+The Parrot FAQ.
+
+=item F<gettingstarted.pod>
+
+The Parrot Developer FAQ.[3]
+
+=item F<glossary.pod>
+
+A guide to some of the jargon which crops up repeatedly in Parrot development
+and throughout the documentation.
+
+=item F<html/>
+
+This subdirectory contains an html version of Parrot's Documentation Set.
+
+=item F<imcc/>
+
+This subdirectory contains documentation on Parrot's Intermediate Code
+Compiler (IMCC).
+
+=item F<index/>
+
+This subdirectory contains the json formatted files with which to generate
+Parrot's html Documentation Set.
+
+=item F<intro.pod>
+
+An introductory article on what Parrot is and how to do some interesting
+things with it.
+
+=item F<memory_internals.pod>
+
+An introduction to the Parrot GC subsystem
+
+=item F<multidispatch.pod>
+
+An (outdated document) on Parrot's multimethod dispatch for binary opcode
+functions.
+
+=item F<optable.pod>
+
+An ALPHA pod, describing the PGE operator precedence table and parser.
+
+=item F<overview.pod>
+
+An overview of Parrot's architecture and design.
+
+=item F<parrotbyte.pod>
+
+The Parrot bytecode format.
+
+=item F<parrothist.pod>
+
+A document which records Parrot source code releases, and their release
+managers.
+
+=item F<parrot.pod>
+
+A general document for the uninitiated which points to several "good starting
+points" throughout Parrot's Documentation Set.
+
+=item F<pct/>
+
+This subdirectory contains documentation on the Parrot Compiler Toolkit.
+
+=item F<pdds/>
+
+This subdirectory contains all of the current Parrot Design Documents (PDDs).
+PDDs are detailed guides to the design of the various Parrot subsystems,
+I<e.g.,> F<pdd03_calling_conventions.pod> specifies Parrot's inter-routine
+calling conventions.
+
+=item F<pmc/>
+
+This subdirectory contains documentation on several of the PMC types available
+to Parrot.
+
+
+=item F<pmc2c.pod>
+
+A document on the F<tools/build/pmc2c.pl> and how to use the tool to generate
+C code files from PMC definition files.
+
+=item F<pmc.pod>
+
+A general overview of PMC.
+
+=item F<porting_intro.pod>
+
+"This document is an introduction to porting the optional subsystems of Parrot
+onto a new architecture once the core successfully builds."
+
+=item F<project/>
+
+This subdirectory contains documentation important to Parrot Developers and
+administrators, I<e.g.,> F<docs/projects/release_manager_guide.pod>.
+
+=item F<req/>
+
+This subdirectory contains a document on "Model Users For Parrot Design
+Decisions."[4]
+
+=item F<resources/>
+
+This subdirectory contains various "resource" files, I<e.g.,>
+F<parrot_logo.png>, F<parrot.css>, etc.
+
+=item F<running.pod>
+
+Brief descriptions of the different executables and how to run them.
+
+=item F<stability.pod>
+
+"This document classifies Parrot components and interfaces based on their
+stability."
+
+=item F<submissions.pod>
+
+This is a document on "[h]ow to submit bug reports, patches and new files to
+Parrot."
+
+=item F<tests.pod>
+
+Hints on writing tests for the Parrot interpreter.
+
+=item F<translations/>
+
+This subdirectory contains multiple translations of Parrot's plaintext
+'README', I<e.g.,> F<README.deutsch>, F<README.espanol>, etc.
+
+=item F<user/>
+
+This subdirectory contains various documents of general interest to users,
+wanting to target Parrot.
+
+=item F<vtables.pod>
+
+A brief introduction to the vtable at the heart of all PMCs, and how to
+implement your own PMC type.
+
+=back
+
+=head1 NOTES
+
+[1] The contents of this 'README.pod' are, at present, tentative and,
+therefore, are subject to change.
+
+[2] We should change the name of this FAQ to better conform with the purpose
+of the FAQ. F<compiler_faq.pod> is far too ambiguous to be helpful.
+
+[3] We should change the name of this FAQ to better conform with the purpose
+of the FAQ. F<getttingstarted.pod> is far too general and implies something
+other than the Parrot Developer FAQ.
+
+[4] Is there any reason to retain this document? It seems, ten years later,
+more of a curiousity than an actual guide.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012, Parrot Foundation.
+
+=cut
View
24 binaries/README.pod
@@ -0,0 +1,24 @@
+# Copyright (C) 2001-2012, Parrot Foundation.
+
+=pod
+
+=head1 NAME
+
+docs/binaries/README.pod - Readme file for the 'docs/binaries/' directory.
+
+=head1 DESCRIPTION
+
+This directory contains the *.pod files to the installable binaries in the
+Parrot distribution. These files are also (or soon will be) used to generate
+*roff pages.[1]
+
+=head1 NOTES
+
+[1] The probable location and name of the conversion script will be,
+F<tools/docs/mk_pod2man.pl>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2012, Parrot Foundation.
+
+=cut
View
54 binaries/ops2c.pod
@@ -0,0 +1,54 @@
+# Copyright (C) 2011, Parrot Foundation.
+
+=head1 Name
+
+ops2c - Convert Parrot opcodes to C
+
+=head1 Description
+
+Translate Parrot opcode files (.ops) to C files.
+
+=head1 Usage
+
+ops2c [option]
+
+=head2 Command line Options
+
+For help, use :
+
+ -h
+ --help
+
+To generate the C code for core ops (must be run from within Parrot's build directory), use :
+
+ -c
+ --core
+
+To generate the C code for dynamic ops in a single .ops file, use :
+
+ -d <file.ops>
+ --dynamic <file.ops>
+
+To suppress error messages, use :
+
+ -q
+ --quiet
+
+To suppress #line directives in generated C code (line numbers are not currently supported), use :
+
+ -n
+ --no-lines
+
+For debugging option :
+To perform all processing without writing to any files, use :
+
+ -g
+ --debug
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
View
80 binaries/parrot-nqp.pod
@@ -0,0 +1,80 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 Name
+
+parrot-nqp - Not Quite Perl (6)
+
+=head1 Description
+
+This is "Not Quite Perl (6)" -- a High Level Language (HLL) which allows one to
+write Perl6-like code. The key feature of NQP is that it's designed to be an
+easy-to-parse subset of Perl 6. It is geared towards being a high-level way to
+create transformers for Parrot (especially HLL compilers). It is based on
+PCT::HLLCompiler.
+
+NQP is used as a bootstrapping language in for Rakudo, and hence developed
+outside of the main Parrot git repository. It is occasionally snapshotted into
+the main Parrot codebase so it can be bundled with Parrot releases and be used
+by core Parrot developers as well as HLL developers.
+
+=head1 Usage
+
+parrot-nqp <file>
+
+=head2 Command Line Usage
+
+For help use :
+
+ -h
+ --help
+
+To show version use :
+
+ -v
+ --version
+
+To display the parse tree for regular expression use :
+
+ --target=parse
+
+To dispaly the PIR subroutine gererated to match the regular expression use :
+
+ --target=pir
+
+For dumper use :
+
+ --dumper=s
+
+To trace use :
+
+ -t=s
+ --trace=s
+
+For encoding use :
+
+ --encoding=s
+
+To combine use :
+
+ --combine
+
+For stage stats use :
+
+ --stagestats
+
+For backtrace use :
+
+ --ll-backtrace
+
+For output use :
+
+ -o=s
+ --output=s
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
View
98 binaries/parrot-prove.pod
@@ -0,0 +1,98 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 Name
+
+parrot-prove - Prove is a PIR-based TAP (Test Anything Protocol) Harness
+
+=head1 Description
+
+It eats test output (i.e. is a TAP consumer) and tells humans if the
+test suite passed, and if not, which kind of pretty colors of smoke
+came out. It is mostly equivalent to 'prove' from Perl 5.
+
+=head1 Usage
+
+parrot-prove [option] [files]
+
+=head2 Command line boolean options
+
+To print all test lines use :
+
+ -v
+ --verbose
+
+To run the tests in random order use :
+
+ -s
+ --shuffle
+
+To show failed tests use :
+
+ -f
+ --failures
+
+To show comments use :
+
+ -o
+ --comments
+
+To ignore exit status from test scripts use :
+
+ --ignore-exit
+
+To merge test scripts STDERR with their STDOUT use :
+
+ -m
+ --merge
+
+To run tests in reverse order use :
+
+ --reverse
+
+To suppress some test output while running tests use :
+
+ -q
+ --quiet
+
+To print only summary result use :
+
+ -Q
+ --QUIET
+
+To show only results with TODO or SKIP directives use :
+
+ --directives
+
+To normalize TAP output in verbose output use :
+
+ --normalize
+
+To display help use :
+
+ -h
+ --help
+
+To display version use :
+
+ -v
+ --version
+
+=head2 Command line options that take arguments
+
+To interpreter to run the tests (' ' for compiled tests.) use :
+
+ -e
+ --exec
+
+To store the resulting TAP in an archive file use :
+
+ -a
+ --archive
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
View
417 binaries/parrot.pod
@@ -0,0 +1,417 @@
+# Copyright (C) 2011, Parrot Foundation.
+
+=pod
+
+=head1 NAME
+
+parrot - Parrot Virtual Machine
+
+=head1 SYNOPSIS
+
+B<parrot> [-options] <file> [arguments ...]
+
+=head1 DESCRIPTION
+
+Parrot is a virtual machine designed to efficiently compile and execute
+bytecode for dynamic languages. Parrot currently hosts a variety of language
+implementations in various stages of completion, including Tcl, Javascript,
+Ruby, Lua, Scheme, PHP, Python, Perl 6, APL, and a .NET bytecode translator.
+Parrot is not about parrots, but we are rather fond of them, for obvious
+reasons.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>
+
+=item B<--help> Print the option summary on the command line.
+
+=item
+
+=item B<-V>
+
+=item B<--version> Print version information and exit.
+
+=item
+
+=item B<-I>
+
+=item B<--include> Add C<path> to the include search path.
+
+=item
+
+=item B<-L>
+
+=item B<--library> Add C<path> to the library search path.
+
+=item
+
+=item B<--hash-seed> [hexnum]
+
+=over 11
+
+Sets the hash seed to the specified value. This option is useful for debugging intermittent
+failures, but should I<not> be used in production. For more information about this option,
+I<see> F<docs/dev/profiling.pod>, F<docs/project/hacking_tips.pod>, F<docs/running.pod>,
+and F<docs/submissions.pod>.
+
+=back
+
+=item B<-X>
+
+=item B<--dynext> Add C<path> to the dynamic extension search path.
+
+=back
+
+=head2 Run core options
+
+These options select the runcore, which is useful for performance tuning and debugging. For more
+information about these options, I<see> the "About runcores" section in F<docs/running.pod>.
+
+=over 4
+
+=item B<-R>
+
+=item B<--runcore> [CORE]
+
+=over 11
+
+Select the runcore. The following cores are available in Parrot, but not all
+may be available on your system:
+
+ slow, bounds bounds checking core (default)
+
+ fast bare-bones core without bounds-checking or
+ context-updating
+
+ subprof subroutine-level profiler
+ (see POD in 'src/runcore/subprof.c')
+
+ trace bounds checking core with trace info
+ (see 'parrot --help-debug')
+
+ profiling see 'docs/dev/profilling.pod'
+
+ gcdebug performs a full GC run before every op dispatch
+ (good for debugging GC problems)
+
+=back
+
+=item B<-p>
+
+=item B<--profile> Run with the slow core and print an execution profile.
+
+=item
+
+=item B<-t>
+
+=item B<--trace> Run with the slow core and print trace information to B<stderr>.
+
+=over 11
+
+I<See> C<parrot --help-debug> for available flag bits.
+
+=back
+
+=back
+
+=head2 VM options
+
+=over 4
+
+=item B<-D>
+
+=item B<--parrot-debug>[=HEXFLAGS]
+
+=over 11
+
+Turn on interpreter debug flag. I<See> C<parrot --help-debug> for available flag bits.
+
+=back
+
+=item B<--help-debug> Print the summary of debugging and tracing flag bits.
+
+=item
+
+=item B<-w>
+
+=item B<--warnings> Turn on warnings.
+
+=over 11
+
+I<See> C<parrot --help-debug> for available flag bits.
+
+=back
+
+=item B<-G>
+
+=item B<--no-gc> Turn off GC.
+
+=over 11
+
+This may prove useful for finding GC-related bugs.
+
+=back
+
+=over 11
+
+=item Note:
+
+Do not use this option for longer running programs: since memory is no longer recycled, it may
+quickly become exhausted.
+
+=back
+
+=item B<-g>
+
+=item B<--gc> [GC-type]
+
+=back
+
+=head3 GC MS2 options
+
+=over 4
+
+=item B<--gc-dynamic-threshold>=percentage
+
+=over 11
+
+Maximum memory wasted by GC
+
+=back
+
+=item B<--gc-min-threshold>=Kb
+
+=back
+
+=head3 GC GMS options
+
+=over 4
+
+=item B<--gc-nursery-size>=percent of system
+
+=over 11
+
+Size of gen0 (default 2)
+
+=back
+
+=item B<--gc-debug> Turn on GC (Garbage Collection) debugging.
+
+=over 11
+
+This imposes some stress on the GC subsystem and can considerably slow
+down execution.
+
+=back
+
+=item B<--leak-test|--destroy-at-end>
+
+=over 11
+
+Free all memory of the last interpreter. This is useful when running leak
+checkers.
+
+=back
+
+=item B<-.>
+
+=item B<--wait> Read a keystroke before starting.
+
+=over 11
+
+This is useful when you want to attach a debugger on platforms such as Windows.
+
+=back
+
+=item B<--runtime-prefix>
+
+=over 11
+
+Print the runtime prefix path and exit.
+
+=back
+
+=back
+
+=head2 Compiler options
+
+=over 4
+
+=item B<-d>
+
+=item B<--imcc-debug>=[HEXFLAGS]
+
+=over 11
+
+The B<-d> switch takes an optional argument, consisting of a hexadecimal value
+of debug bits. If no value is supplied, 'debug' is set to 1.
+
+To list the individual bits on the command line, use the B<--help-debug> switch.
+
+To produce a vary large output on F<stderr>, run C<"parrot B<-d 0ffff> ...">.
+
+=back
+
+=item B<-v>
+
+=item B<--verbose> One C<-v> shows which files are worked on and prints
+
+=over 11
+
+a summary over register usage and optimization stats per I<subroutine>. With
+two C<-v> switches, C<parrot> prints a line per individual processing step too.
+
+=back
+
+=item B<-E>
+
+=item B<--pre-process-only>
+
+=over 11
+
+Preprocess source file (expand macros) and print result to C<stdout>:
+
+ $> parrot -E t/op/macro_10.pasm
+ $> parrot -E t/op/macro_10.pasm | parrot -- -
+
+=back
+
+=item B<-o>
+
+=item B<--output>=FILE Act like an assembler, but do not execute the code,
+
+=over 11
+
+unless the B<-r> is supplied as well. If 'outputfile' ends with F<.pbc>,
+'parrot' will write a PBC file. If it ends with F<.pasm>, 'parrot' will output
+a PASM file, even from PASM input. This can be useful when needing to check
+various optimizations, including C<-Op>.
+
+=back
+
+=item B<--output-pbc> Act like an assembler, but always output bytecode,
+
+=over 11
+
+even if the output file does not end in F<.pbc>
+
+=back
+
+=item B<-O>
+
+=item B<--optimize>[=LEVEL]
+
+=over 11
+
+Optimization levels
+
+ -O0 no optimization (default)
+ -O1 optimizations without life info (e.g. branches)
+ -O same
+ -O2 optimizations with life info
+ -Op rewrite I and N PASM registers most used first
+ -Ot select fastest runcore
+ -Oc turns on the optional/experimental tail call optimizations
+
+I<See> F<docs/dev/optimizer.pod> for more information on the optimizer.
+
+=back
+
+=over 11
+
+=item Note:
+
+Optimization is currently an experimental feature and these options are likely to change.
+
+=back
+
+=item B<-a>
+
+=item B<--pasm> Assume PASM input on C<stdin>.
+
+=item B<-c>
+
+=item B<--pbc> Assume PBC file on C<stdin> and execute it.
+
+=over 11
+
+NOTE: If whitespace separates the B<-d> switch from the argument, the argument
+I<must> start with a number, I<i.e.>, a decimal digit.
+
+=back
+
+=item B<-r>
+
+=item B<--run-pbc> Only useful after C<-o> or C<--output-pbc>.
+
+=over 11
+
+Execute the program from the compiled in-memory image. If two C<-r> options are
+supplied, the F<.pbc> file is read from disc and executed. This is needed,
+primarily, for tests.
+
+=back
+
+=item B<-y>
+
+=item B<--yydebug> Turn on yydebug in F<yacc>/F<bison>.
+
+=back
+
+=head2 <file>
+
+If the file ends in F<.pbc> it will be interpreted immediately.
+
+If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
+parsed as PIR code. In both cases, it will then be executed, unless the C<-o>
+flag was supplied.
+
+If the C<file> is a single dash, input from C<stdin> is read.
+
+=head2 [arguments ...]
+
+Optional arguments passed to the running program as ARGV. The program is
+assumed to know what to do with the arguments.
+
+=head1 ENVIRONMENT
+
+=over 4
+
+=item PARROT_RUNTIME
+
+If this environment variable is set, parrot will use this path as its runtime
+prefix instead of the compiled-in path. This is useful if you want to execute
+a version of parrot different from the one on the "compiled-in" path.
+
+=item PARROT_GC_DEBUG
+
+Turn on the I<--gc-debug> flag.
+
+=back
+
+=head1 SEE ALSO
+
+'docs/running.pod' Additional information on command line options.
+
+http://www.parrot.org/ The official Parrot web site.
+
+http://docs.parrot.org/ Parrot's official documentation site.
+
+http://parrot.github.com/ An alternative documentation site.
+
+=head1 REPORTING BUGS
+
+For information on how to submit a bug report, I<see> F<docs/submissions.pod>.
+
+=head1 AUTHORS
+
+Parrot is a product of the contributions of a great many people. For a list of
+most of these people, I<see> F<CREDITS>.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001-2011, Parrot Foundation.
+
+=cut
View
36 binaries/parrot_config.pod
@@ -0,0 +1,36 @@
+# Copyright (C) 2011 Parrot Foundation.
+
+=head1 Name
+
+parrot_config - Parrot Configuration
+
+=head1 DESCRIPTION
+
+parrot_config can be used find out compile-time configuration information about
+the Parrot executable.
+
+=head1 SYNOPSIS
+
+To print every available key:
+
+ parrot_config --dump
+
+With specific key it will print only it's corresponding value.
+
+To get the current version of Parrot:
+
+ parrot_config VERSION
+
+To get a descriptive version string that will uniquely identify
+commits which are not releases:
+
+ parrot_config git_describe
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to
+'parrot-dev@parrot.org'. You can also join Parrot IRC channel: #parrot
+on irc.parrot.org .
+
+=cut
View
73 binaries/parrot_nci_thunk_gen.pod
@@ -0,0 +1,73 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 Name
+
+parrot_nci_thunk_gen - Create Parrot NCI thunks
+
+=head1 Description
+
+This utility creates C file of routines suitable for use as Parrot Native Call Interface thunks.
+
+=head1 Usage
+
+ parrot_nci_thunk_gen [option] -o output_c_file.c < input_signature_list.nci
+
+=head2 Command line Options
+
+To print help message and exit use :
+
+ --help
+
+To print version number of this utility use :
+
+ --version
+
+Not to complain about duplicated signatures (default is to warn) use :
+
+ -f
+ --no-warn-dups
+
+To output a thunk file suitable for inclusion in Parrot core (default is no) use :
+
+ --core
+
+To use default values for loader-name, loader-storage-class, and target suitable
+for use in Parrot dyntex library use :
+
+ --dyntex
+
+To specify output file use :
+
+ -o
+ --output <file>
+
+To select what to output (valid operation are 'head', 'thunks', 'loader',
+'loader-dyntex', 'coda', 'all', 'all-dyntex', 'names' and 'signatures')
+(default is 'all') use :
+
+ --target <target>
+
+To set storage class used for the thunks (default value is static) use :
+
+ --thunk-storage-class <storage class>
+
+To set the prototype used for the thunk function names.Must be a printf
+format with arity 1 (default value is 'pcf_%s') use :
+
+ --thunk-name-proto <printf prototype>
+
+To set the storage class used for the loader funtion (default value is none) use :
+
+ --loader-storage-class
+
+To set the name used for the leader function (default value is 'Parrot_load_nci_thunks') use :
+
+ --loader-name
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
View
95 binaries/parrotbug.pod
@@ -0,0 +1,95 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 Name
+
+parrotbug.pod - Parrot bug report
+
+=head1 Description
+
+A program to help generate bug reports about parrot, and mail them.
+It is designed to be used interactively. Normally no arguments will
+be needed.
+
+=head1 Usage
+
+parrotbug [option] [action]
+
+=head2 Comman line Options
+
+To report successful build on this system to parrot developers use :
+
+ --ok
+
+Only use C<--ok> if everything was ok.If there were any problems at all, use :
+
+ --nok
+
+It is used to Report unsuccessful build on system.
+
+To include specific summary with the message use :
+
+ --summary <summary>
+
+To include specific category to the bug report use :
+
+ --category <category>
+
+To include severity to the bug report use :
+
+ --severity <severity>
+
+To set your emal addres use :
+
+ --from <address>
+
+To open editor to use for editing the bug report use :
+
+ --editor <editor>
+
+Not to send a bug report which receive acknowledgement use :
+
+ --ack
+ --noack
+
+To open a file containing the body of the report use :
+
+ --input-file
+
+Use this to quickly send a prepared message.
+
+To view file where parrotbug will save it's bug report use :
+
+ --output-file
+
+Note: you will be prompted if the program miss some information.
+
+=head2 Command line Actions
+
+To dump message use :
+
+ --dump
+
+To save message use :
+
+ --save
+
+To print help message and exit after that use :
+
+ --help
+
+To print version information and exit after that use :
+
+ --version
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
+
+
+
+
+
View
67 binaries/pbc_to_exe.pod
@@ -0,0 +1,67 @@
+# Copyright (C) 2011, Parrot Foundation.
+
+=head1 Name
+
+pbc_to_exe - Generate executables from Parrot bytecode
+
+=head1 Description
+
+This utility compiles bytecode to native executables. These are called
+"fakecutables", because they are actually just the bytecode packaged up as raw
+data inside a C skeleton.
+
+=head1 Usage
+
+pbc_to_exe [option] <file>
+
+=head2 Command line Options
+
+For help use :
+
+ -h
+ --help
+
+To install use :
+
+ -i
+ --install
+
+To runcore or to change runcore use :
+
+ -R
+ --runcore=slow|fast
+
+For output file use :
+
+ -o
+ --output=FILE
+
+To change garbage collector algorithm use :
+
+ --gc=ms2|gms
+
+C<gms> is default. C<ms2> is older and slower
+
+=head2 Synopsis
+
+ pbc_to_exe my.pbc
+
+Will generate :
+
+ my.exe
+
+And
+
+ pbc_to_exe my.pbc --install
+
+Will generate :
+
+ installable_my.exe
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
View
147 binaries/plumage.pod
@@ -0,0 +1,147 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 Name
+
+plumage.pod - Parrot Plumage
+
+=head1 Description
+
+Parrot Plumage is the Parrot Virtual Machine module ecosystem. It includes
+tools to search metadata, handle dependencies, install modules, and so forth.
+
+=head1 Usage
+
+plumage [<options>] <command> [<arguments>]
+
+=head1 Command line options
+
+For help about options and commands you can type:
+
+ plumage usage
+
+Or to use command line option help :
+
+ plumage -h
+ plumage --help
+
+To read additional config file use :
+
+ -c
+
+Or if you want to use specific path use :
+
+ --config-file=<path>
+
+To ignore any failed build stages use :
+
+ -i
+ --ignore-fail
+
+To ignore fails only for specific stage use :
+
+ --ignore-fail=<stage>
+
+You can repeat to select more than one stage.
+Not to ignore fail in specific stage use :
+
+ --ignore-fail=<stage>=0
+
+=head1 Command line commands
+
+=head2 General commands
+
+To start interactive command-line interface (default with no commands) use :
+
+ cli
+
+To display Plumage version and copyright statement use :
+
+ version
+
+To display help message on specific command use :
+
+ help [<command>]
+
+=head2 Query metadata and project info
+
+To list all known projects use :
+
+ projects
+
+To show status of specific project use :
+
+ status [<project>]
+
+To display detailed description of specific project use :
+
+ info <project>
+
+To dispay JSON metadata for specific project use :
+
+ metadata <project>
+
+To Show dependencies for specific project use :
+
+ show-deps <project>
+
+To display top directory for specific project use :
+
+ project-dir <project>
+
+=head2 Perform actions on a project
+
+To downloads source code for specific project use :
+
+ fetch <project>
+
+To update source code for specific project use (it fall bacj to fetch) :
+
+ update <project>
+
+To configure source code for specific project use (runs 'update' furst) :
+
+ configure <project>
+
+To build specific project in current directory (runs 'configure' first) :
+
+ build <project>
+
+To run test suite for specific project use (runs 'build' first) :
+
+ test <project>
+
+To send test result po Parrot's Smolder server use (runs 'build' first) :
+
+ smoke <project>
+
+To install specific project use (runs 'test' first) :
+
+ install <project>
+
+To uninstall specific project from system use (not always available) :
+
+ uninstall <project>
+
+To perform basic cleanup of source tree for specific project use :
+
+ clean <project>
+
+To remove all generated files during the build process for specific project use :
+
+ reaclean <project>
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
+
+
+
+
+
+
+
+
View
40 binaries/winxed.pod
@@ -0,0 +1,40 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 Name
+
+winxed.pod - The Winxed Language
+
+=head1 Description
+
+This is Winxed, a High Level Language (HLL) that is packaged with Parrot
+for tool, library and language development.
+
+Winxed is Javascript-ish. If you are looking for something more Perl-ish,
+you want NQP.
+
+=head1 Usage
+
+winxed [option] [program] [args]
+
+=head2 Command line otions
+
+ '-c' : is used to compile to pir.
+ '-e==s' : is used to evaluate.
+ '-o==s' : is used to get Object name.
+ '-target=s' : is used to set target type.
+ '-L=s' : is used to add to parrot library search path.
+ '-I=s' : is used to add to parrot include search path.
+ '-X=s' : is used to add to parrot dyntex search path.
+ '--debug' : is used to set debug mode.
+ '--nowarn' : is used to hide warnings.
+ '--noan' : is used to hide code annotations.
+ '--help' : is used to show help for options.
+ '--version' : is used to show the version of winxed and exit.
+
+=head1 Help
+
+For more help or any other question you go to L<http://parrot.org> or
+L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
+You are also invited to join the #parrot IRC channel on irc.parrot.org.
+
+=cut
View
62 book/draft/README.pod
@@ -0,0 +1,62 @@
+# Copyright (C) 2001-2012, Parrot Foundation.
+
+=pod
+
+=head1 NAME
+
+docs/book/draft/README.pod - Readme to a series of draft documents on Parrot
+development.
+
+=head1 DESCRIPTION
+
+The book will contain the following chapters:
+
+=over 4
+
+=item 1. Overview
+
+=item 2. Getting Started
+
+=item 3. Parrot Intermediate Representation (PIR)
+
+=item 4. Compiler Tools (PCT)
+
+=item 5. Grammar Engine (PGE)
+
+=item 6. Grammar Actions (NQP)
+
+=item 7. Dynamic C-level Objects (PMCs)
+
+=item 8. Dynamic Opcodes
+
+=item 9. Parrot Assembly Language (PASM)
+
+=item 10. Instruction Reference
+
+=item 11. Directive Reference
+
+=item 12. Operator Reference
+
+=item Appendix A. Glossary
+
+=item Appendix B. Patch Submission
+
+=item Appendix C. Command-Line Options
+
+=item Appendix D. Build Options
+
+=item Appendix E. Source Code
+
+=back
+
+=head1 NOTE
+
+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).
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001-2012, Parrot Foundation.
+
+=cut
View
314 book/draft/appa_glossary.pod
@@ -0,0 +1,314 @@
+=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 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 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 the Parrot git
+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 clone of the git repository and
+then create diffs using the command C<git 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.pod parrot_changed/README.pod
+
+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.pod 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 git 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
306 book/draft/appc_command_line_options.pod
@@ -0,0 +1,306 @@
+=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 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 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 * Git
+
+Git is the source control system that is used by the Parrot project.
+You need git to clone the latest version of the source code. You can
+get git at L<http://git-scm.com>, 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 compiler IMCC. These are not necessary most of the time
+unless you are planning to hack on IMCC 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 book/draft/appe_source_code.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head1 Use the source
+
+X<Parrot;source code>
+The second step to participating in Parrot development is to get a