Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Comparing changes

Choose two branches to see what's changed or to start a new pull request. If you need to, you can also compare across forks.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also compare across forks.
base: master
...
compare: soh-cah-toa/tt-2155
Checking mergeability… Don't worry, you can still create the pull request.
  • 19 commits
  • 18 files changed
  • 9 commit comments
  • 1 contributor
Commits on Jul 17, 2011
@soh-cah-toa soh-cah-toa Added a README.pod file for the "compilers" directory. 9902af7
Commits on Jul 18, 2011
@soh-cah-toa soh-cah-toa Converted examples/README to POD format and updated a lot of the info…
…rmation in it.
b41d57d
@soh-cah-toa soh-cah-toa Changed several C<> tags to F<>. 754491d
@soh-cah-toa soh-cah-toa Changed several C<> tags to F<> in compilers/README.pod. 2fa333c
@soh-cah-toa soh-cah-toa I made a copy/paste error in the previous commit. Now the C<> tags ar…
…e F<>.
b01bd79
Commits on Aug 01, 2011
@soh-cah-toa soh-cah-toa Changed previous README's to plain text. Future commits will use plai…
…n text as well.
0b6b4ca
@soh-cah-toa soh-cah-toa Rewrote README in 'editor' directory. 7b85621
@soh-cah-toa soh-cah-toa Added README to 'config' directory. b72b1c5
@soh-cah-toa soh-cah-toa Added README to 'docs' directory. 7818635
@soh-cah-toa soh-cah-toa Added README to 'ext' directory. d9f642b
@soh-cah-toa soh-cah-toa Added README for 'frontend' directory. 79bb28e
@soh-cah-toa soh-cah-toa Added README to 'include' directory. c59bffe
@soh-cah-toa soh-cah-toa Added README to 'lib' directory. 99c3f73
Commits on Aug 12, 2011
@soh-cah-toa soh-cah-toa Added README to 'runtime' directory. d7539e4
@soh-cah-toa soh-cah-toa Added README to 'src' directory. f798be4
@soh-cah-toa soh-cah-toa Renamed src/dynpmc/README.pod to dynpmc.pod and moved it into the 'do…
…cs' directory as this is a more appropriate place for documentation like this.
f0b754f
Commits on Aug 18, 2011
@soh-cah-toa soh-cah-toa Added README to 'tools' directory. 061c618
Commits on Aug 28, 2011
@soh-cah-toa soh-cah-toa Corrected copyright notices in README files so that they are for 2011…
… only.
2d781c5
Commits on Sep 24, 2011
@soh-cah-toa soh-cah-toa Changed format of compilers/README to Markdown. This is a test to see…
… if GitHub will render it properly without an .md file extension.
cec66a1
View
3  MANIFEST
@@ -26,6 +26,7 @@ RESPONSIBLE_PARTIES [main]doc
TODO [devel]doc
VERSION [devel]
api.yaml []
+compilers/README.pod []doc
compilers/data_json/Defines.mak [data_json]
compilers/data_json/JSON.nqp [data_json]
compilers/data_json/JSON_README.pod []doc
@@ -420,7 +421,7 @@ editor/pasm.vim []
editor/pir-mode.el []
editor/pir_vim.in []
editor/pmc.vim []
-examples/README [examples]
+examples/README.pod [examples]
examples/benchmarks/addit.pasm [examples]
examples/benchmarks/addit.pir [examples]
examples/benchmarks/addit.pl [examples]
View
46 compilers/README
@@ -0,0 +1,46 @@
+## NAME
+
+compilers - various compilers used by Parrot
+
+## DESCRIPTION
+
+The *compilers* directory contains the source files for several compilers that
+are used by Parrot such as IMCC and PGE. For more detailed information on
+these, please see their respective `README` files in the subdirectories listed
+below.
+
+## SUBDIRECTORIES
+
+* data_json
+
+Source files for the JavaScript Object Notation (JSON) compiler. Used when
+generating a JSON representation of a PMC.
+
+* imcc
+
+Source files for the Intermediate Code Compiler (IMCC). Translates PIR files
+into Parrot bytecode.
+
+* opsc
+
+Source files for the opcode compiler (a.k.a. ops2c). Converts opcode definition
+files into C code.
+
+* pct
+
+Source files for the compiler used by the Parrot Compiler Toolkit (PCT).
+
+* pge
+
+Source files for the compiler used by the Parrot Grammar Engine (PGE). This is
+an implementation of Perl 6 regexes.
+
+* tge
+
+Source files for the compiler used by the Tree Grammer Engine (TGE). This is the
+tool used to transform the trees output by the PGE into a Parrot Abstract
+Syntax Tree (PAST).
+
+## COPYRIGHT
+
+Copyright (C) 2011, Parrot Foundation.
View
39 config/README
@@ -0,0 +1,39 @@
+== NAME ==
+
+config - modules used by the configuration process
+
+== DESCRIPTION ==
+
+The 'config' directory contains all the Perl 5 modules that are used by
+Configure.pl during the configuration process. They are split into
+several subdirectories (listed below) based upon their package name.
+
+== SUBDIRECTORIES ==
+
+* auto
+
+Modules that perform system probes for determining CPU architecture, OS, C
+compiler, installed packages, etc.
+
+* gen
+
+Modules for generating files based on the platform-specific data collected by
+the auto::* modules. This includes the Makefile, header files, core PMC's,
+etc.
+
+* init
+
+Modules for setting up the install path, platform hints, manifest checking,
+optimizations, etc.
+
+* inter
+
+Modules for "interrupting" the user (if --ask was given to Configure.pl)
+to set certain configurations by hand such as what compiler, linker, C
+libraries, lexer/parser should be used, whether debugging should be enabled,
+what flavor of make is installed, etc.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
74 docs/README
@@ -0,0 +1,74 @@
+== NAME ==
+
+docs - Parrot documentation
+
+== DESCRIPTION ==
+
+The 'docs' directory houses the documentation related to all the different
+areas of Parrot. They are all written in POD format.
+
+== SUBDIRECTORIES ==
+
+* book
+
+The 'Parrot Developer's Guide: PIR' book. Contains both the published edition
+and a rough draft.
+
+* deprecations
+
+Records all the deprecations since the 2.6 supported release. Also contains
+documentation explaining Parrot's deprecation policy.
+
+* dev
+
+Developer documentation. Includes topics such as calling conventions,
+long option parsing, function decorations, etc.
+
+* imcc
+
+Documents describing the operations of the Intermediate Code Compiler (IMCC).
+
+* index
+
+JSON files that catalogue all the files in the 'docs' directory.
+
+* pct
+
+Introductory documentation on the Parrot Compiler Toolkit (PCT).
+
+* pdds
+
+Parrot Design Documents (PDDS). These documents describe the inner architecture
+of the virtual machine. Includes topics such as PMC's, multiple dispatch,
+garbage collection, etc.
+
+* pmc
+
+Polymorphic Container (PMC) documentation.
+
+* project
+
+Tips and guidelines for Parrot contributers. Includes topics such as release
+management, cage cleaning, using Git, etc.
+
+* req
+
+Mock "requests" that give Parrot a design direction.
+
+* resources
+
+Resources used by the Parrot website including images, stylesheets, etc.
+
+* translations
+
+Translations of the main README. Includes languages such as Spanish, French,
+Polish, and more.
+
+* user
+
+User documentation for PIR.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
74 docs/dynpmc.pod
@@ -0,0 +1,74 @@
+# Copyright (C) 2001-2011, Parrot Foundation.
+
+=head1 OVERVIEW
+
+Dynamic PMC's are special in that they are loaded at runtime. This is useful
+for when you'd like to create your own custom PMC instead of using one of the
+core PMC's.
+
+A PMC called C<Foo> is defined in F<src/dynpmc/foo.pmc> which is provided as an
+example case.
+
+=head1 CREATING A DYNAMIC PMC
+
+=over 4
+
+=item 1
+
+First, you must create a C<.pmc> file to place the PMC's definition in. The
+F<tools/dev/gen_class.pl> script is provided for creating a template PMC file.
+
+There are some differences you have to be aware of when creating dynamic PMC's.
+
+When declaring a dynamic PMC, you must use the C<dynpmc> modifier. For example:
+
+ pmclass TclString extends TclObject dynpmc ... { ... }
+
+Note that regular (non-dynamic) PMC's have a type id C<enum_class_PMCNAME> but
+dynamic PMC's do not. Instead, a dynamically-chosen value is assigned at runtime
+so that when you refer to the type of the class, you must dynamically
+determine the PMC type. For example, the C<scalar> builtin has the luxury of
+knowing at compile time what the class number of its child, C<String>, is by
+using:
+
+ if (type == enum_class_String) { ... }
+
+However, a dynamic PMC such as C<TclInt> instead must perform a runtime lookup
+of its corresponding C<TclString> PMC using the more complicated:
+
+ static INTVAL dynpmc_TclString;
+
+ pmclass TclInt extends TclObject extends Integer dynpmc group tcl_group {
+ void class_init() {
+ if (pass)
+ dynpmc_TclString = Parrot_PMC_typenum(interp,"TclString");
+ }
+ }
+
+If you have a group of related PMC's that are interdependent, use the
+C<group> modifier to build a group library. Then you must specify the group name
+when loading the library with the C<loadlib> opcode. For example:
+
+ pmclass Match extends Hash dynpmc group match_group { ... }
+
+To load this group library, use:
+
+ loadlib $P0, "match_group"
+
+=item 2
+
+To build your dynamic PMC's, create a build target in C<src/dynpmc/Defines.in>.
+This file is included in the main Makefile, so running C<make> will build your
+dymamic PMC's:
+
+ perl Configure.pl
+ make
+
+=item 3
+
+To verify that any recent changes or deprecations don't adversely affect your
+PMC's, run:
+
+ make dynpmc-clean
+
+=back
View
99 editor/README
@@ -0,0 +1,99 @@
+== NAME ==
+
+editor - text editor plugins
+
+== DESCRIPTION ==
+
+The 'editor' directory contains plugins and add-ons for several popular text
+editors. They include syntax-highlighting, automatic indenting, Ctags, etc.
+
+A summary of available plugins can be found by running:
+ `cd editor && make help`
+
++ Vim +
+
+By default, calling `make vim-install` in the 'editor' directory will install
+several files into ~/.vim. You can use the 'VIM_DIR' variable on the command
+line when calling `make` to choose a different target directory for the vim
+files. For example:
+
+ `make vim-install [VIM_DIR=/vim_files_target_directory]`
+
+All these files have the .vim extension: pir.vim (generated from pir_vim.in),
+pasm.vim, and pmc.vim are syntax files; indent_pir.vim is an indent plugin;
+and filetype_parrot.vim is a filetype script that tells vim to associate the
+extensions .pir, .pasm, and .pmc with the right syntax. The syntax files are
+installed to ~/.vim/syntax; filetype_parrot.vim is installed to
+~/.vim/parrot.vim; and indent_pir.vim is copied to ~/.vim/indent/pir.vim. If
+you want indenting, you should also place "filetype indent on" somewhere in
+your ~/.vimrc file.
+
++ Kate +
+
+There is a syntax file for the KDE editor Kate, but it is not built by default.
+You must run:
+
+ `make imc.kate`
+
+in the 'editor' directory to build it.
+
+Copy the imcc.xml file to ~/.kde/share/apps/katepart/syntax.
+
++ Emacs +
+
+The parrot.el file describes the changes to 'c-mode' and 'cperl-mode' required
+to edit Parrot source code. Copy parrot.el to a directory where Emacs looks
+for external packages and add the following to your ~/.emacs file:
+
+ (load "parrot")
+
+Alternatively, to automatically track future changes, you may wish to add this
+to ~/.emacs instead:
+
+ (load-file "/<path-to-parrot>/editor/parrot.el")
+
+Also included is pasm.pl for editing PASM source files. Copy pasm.el to a
+directory where Emacs looks for external packages and add the following to your
+~/.emacs file:
+
+ (load "pasm")
+
+To associate .pasm files with this major mode, add the following to your
+~/.emacs file:
+
+ (add-to-list 'auto-mode-alist (cons "\\.pasm\\'" 'pasm-mode))
+
+Alternatively, you may type 'M-x pasm-mode' for every file that you want to use
+the major mode in.
+
+Additionally, you might also want to add the following to your ~/.emacs file:
+
+ (add-hook 'pasm-mode-hook
+ (function (lambda ()
+ (setq indent-tabs-mode nil))))
+
+This prevents the odd behavior that has been noted when using tabs in the
+PASM mode.
+
++ Ctags +
+
+The main Makefile (not the one in 'editor'), includes several targets for
+generating a tags file. The Exuberant Ctags package must be installed first.
+
+For Vim-compatible tags, run:
+
+ `make tags-vi`
+
+For Emacs-compatible tags, run:
+
+ `make tags-emacs`
+
+There is also the 'tags-xemacs' target which will work with the older XEmacs
+etags (21.5*). Run:
+
+ `make tags-xemacs`
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
108 editor/README.pod
@@ -1,108 +0,0 @@
-
-=head1 NAME
-
-editor/README.pod - Productivity Comes in Pretty Colors
-
-=head1 Syntax Highlighting and Other Editor Assistance
-
-Included in this directory are some add-ins for making working on parrot (or in
-parrot) easier, for various popular editors. Mostly that means
-syntax-highlighting and automatic indenting. Read on to see what's available for
-your favorite editor. For a summary on what is available do
- cd editor && make help
-
-=head2 Vim
-
-By default calling C<make vim-install> in the F<editor/> directory will
-install several files in F<~/.vim>. You can use the variable C<VIM_DIR>
-on the command line by calling C<make> to choose a different target directory
-for the vim files.
-
- make vim-install [VIM_DIR=/vim_files_target_directory]
-
-All these files have the F<.vim>
-extension. F<pir.vim> (generated from F<pir_vim.in>), F<pasm.vim>, and
-F<pmc.vim> are syntax files; F<indent_pir.vim> is an indent plugin;
-and F<filetype_parrot.vim> is a filetype script that tells vim to
-associate the extensions .pir, .pasm, and .pmc with the
-right syntax. The syntax files are installed to F<~/.vim/syntax/>;
-F<filetype_parrot.vim> is installed to F<~/.vim/parrot.vim>;
-F<indent_pir.vim> is copied to F<~/.vim/indent/pir.vim>. If you want
-indenting, you should also place C<filetype indent on> somewhere in
-your F<~/.vimrc>.
-
-=head2 Kate
-
-There is a syntax file for the KDE editor Kate, but it is not built by default.
-Run:
-
- make imc.kate
-
-in F<editor/> to build it.
-
-Copy the file F<imcc.xml> to F<~/.kde/share/apps/katepart/syntax>.
-
-=head2 Emacs
-
-=over 4
-
-=item * Editing the Parrot VM source
-
-In this directory is a F<parrot.el> describing the c-mode and cperl-mode
-changes modifications required to edit the Parrot source code. To install
-the Parrot mode support copy F<parrot.el> to a directory where Emacs looks
-for external packages and add the following to your F<~/.emacs> file:
-
- (load "parrot")
-
-Alternatively, if you're an active Parrot developer, you may wish to add
-this to your .emacs instead, to automatically track future changes:
-
- (load-file "/<path-to-parrot>/editor/parrot.el")
-
-=item * Editing PASM source files
-
-Included here is an Emacs mode for editing pasm files, in F<pasm.el>.
-
-To install the pasm major mode copy F<pasm.el> to a directory where Emacs
-looks for external packages and add the following to your F<~/.emacs> file:
-
- (load "pasm")
-
-To automatically associate .pasm files with this major mode add:
-
- (add-to-list 'auto-mode-alist (cons "\\.pasm\\'" 'pasm-mode))
-
-to your F<~/.emacs> or you can alternatively type C<M-x pasm-mode> for every
-file that you want to use the major mode in.
-
-Additionally, you might want to add:
-
- (add-hook 'pasm-mode-hook
- (function (lambda ()
- (setq indent-tabs-mode nil))))
-
-to F<~/.emacs> as this seems to prevent the odd behavior that is noted when
-using tabs in the pasm mode.
-
-=back
-
-=head2 TAGS file
-
-There is a script here to automatically generate a TAGS file, which works with
-Vim and other editors that recognize ctags-format files. Run
-
- make tags-vi
-
-for Vim-compatible tags or
-
- make tags-emacs
-
-for Emacs-style tags. The tool "exuberant ctags" is required for both. There
-is also the
-
- make tags-xemacs
-
-target which will work with older XEmacs etags (21.5*).
-
-=cut
View
125 examples/README
@@ -1,40 +1,123 @@
+== NAME ==
-The directory 'examples' provides examples of proper,
-and sometimes hillarious, programs for Parrot.
-Most of these examples are tested by test scripts in 't/examples'.
+examples - helpful examples of common tasks with Parrot
-benchmarks - Contains benchmarks. Run them with 'make benchmark_tests'
+== DESCRIPTION ==
+
+The 'examples' directory provides examples of some of the more common - and
+sometimes hillarious - uses of the Parrot virtual machine. If you are new to
+the world of Parrot, browsing through some of these examples can be incredibly
+helpful. Most of these examples are tested by the test files in 't/examples'.
+
+== SUBDIRECTORIES ==
+
+* benchmarks
+
+Benchmark test examples. They can be run with `make benchmark_tests`.
-c - Examples in C
+* c
+
+Examples in C that demonstrate the embedding API and how the Parrot frontend
+interprets bytecode.
+
+* compilers
+
+Example of a compiler called JAPH.
+
+* config
+
+An example demonstrating how Configure.pl works.
+
+* embed
+
+An example of how the embedding API can be used.
+
+* io
+
+Examples of Parrot's IO subsystem in PIR.
+
+* json
+
+Examples demonstrating how to generate a JSON representation of a PMC.
+
+* languages
+
+Contains the source files for the demo languages abc and Squaak.
+Demonstrates how to use the Parrot Compiler Toolkit (PCT).
+
+* library
+
+Examples demonstrating how to use Parrot's runtime libraries in PIR.
+
+* mops
+
+Contains an example called "million ops per second" in various languages which
+calculates a value for M ops/s using integer arithmetic.
+
+* namespace
+
+Examples demonstrating how to use namespaces in PIR.
+
+* nci
+
+Examples demonstrating Parrot's Native Call Interface (NCI).
+
+* opengl
+
+Examples demonstrating how to use the OpenGL library in PIR and Perl 6.
+
+* pasm
+
+Examples of common tasks in Parrot Assembly Language (PASM).
+
+* past
+
+Examples of a PAST to PIR translation.
+
+* pge
+
+Contains an example PIR generated file using the Parrot Grammar Engine (PGE).
+
+* pir
+
+Examples of common tasks in Parrot Intermediate Representation (PIR).
+
+* sdl
+
+Examples demonstrating how to use the Simple DirectMedia Layer (SDL) library in
+PIR.
+
+* shootout
-compilers - Examples for parrot compilers
+Contains the PIR files used for The Computer Language Benchmark Game or The
+Great Computer Languages Shootout.
-io - Examples how PIR and PASM programs talk with the world
+* streams
-japh - Say 'Just another Parrot hacker' in various ways
+Examples demonstrating how to use the Stream library.
-library - Examples on how to use PIR libraries
+* subs
-mops - Million ops per second
+Examples demonstrating how to call subroutines in PIR and PASM.
-nci - Native call interface
+* tcl
-pasm - Examples in Parrot Assembler, PASM
+Examples demonstrating how to create a Tcl/Tk GUI using the NCI.
-past - Examples of PAST, Parrot Abstract Syntax Tree, see pdd26_ast
+* tge
-pge - Parrot grammar engine
+Examples demonstrating the Tree Grammer Engine (TGE).
-pir - Examples in Parrot Intermediate Representation, PIR
+* tools
-sdl - SDL
+Examples of miscellaneous tools such as a bytecode checker and a grep-like
+utility.
-shootout - PIR for the great computer languages shootout at http://shootout.alioth.debian.org/
+* tutorial
-streams - Examples for the streams library
+A PIR tutorial by example.
-subs - calling subroutines in PIR and PASM
+== COPYRIGHT ==
-tge - usage of TGE, see compilers/tge
+Copyright (C) 2011, Parrot Foundation.
-tutorial - a PIR tutorial
View
31 ext/README
@@ -0,0 +1,31 @@
+== NAME ==
+
+ext - extensions to Parrot
+
+== DESCRIPTION ==
+
+The 'ext' directory contains Parrot extensions that are not necessarily
+essential to the functioning of Parrot but, nonetheless, are used frequently
+and extensively by the Parrot developers.
+
+== SUBDIRECTORIES ==
+
+* nqp-rx
+
+Source files for the Not Quite Perl (NQP) compiler with regex support. NQP is a
+very small Perl6-like language designed to be a high level way of creating
+transformers for Parrot.
+
+* Parrot-Embed
+
+Source files for Parrot's embedding interface for Perl 5.
+
+* winxed
+
+Source files for the Winxed compiler. Winxed is a JavaScript-like language for
+easily creating Parrot extensions.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
40 frontend/README
@@ -0,0 +1,40 @@
+== NAME ==
+
+frontend - compiler frontend applications
+
+== DESCRIPTION ==
+
+The 'frontend' directory contains the source files for the compiler frontend and
+other programs that use the embedding API.
+
+== SUBDIRECTORIES ==
+
+* hbdb
+
+The Honey Bee Debugger (HBDB). Parrot's new debugger.
+
+* parrot
+
+The Parrot frontend. The PIR/PASM compiler for libparrot.
+
+* parrot_debugger
+
+The old Parrot debugger.
+
+* pbc_disassemble
+
+Bytecode disassembler. Translates Parrot bytecode (PBC) into Parrot assembly
+language (PASM).
+
+* pbc_dump
+
+Bytecode dumper. Dumps or converts .pbc files into human-readable form.
+
+* pbc_merge
+
+Bytecode merger. Merges multiple .pbc files into a single .pbc file.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
30 include/README
@@ -0,0 +1,30 @@
+== NAME ==
+
+include - header files for Parrot internals
+
+== DESCRIPTION ==
+
+The 'include' directory contains the C header files used by the source code
+making up the actual virtual machine.
+
+== SUBDIRECTORIES ==
+
+* imcc
+
+Header files used by the Intermediate Code Compiler (IMCC). Translates PIR files
+into Parrot bytecode.
+
+* parrot
+
+Header files used by the interals of the virtual machine.
+
+* pmc
+
+Header files containing the exported functions used to manipulate Polymorphic
+Containers (PMC) in C code. The files are auto-generated by the
+tools/build/pmc2c.pl script.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
40 lib/README
@@ -0,0 +1,40 @@
+== NAME ==
+
+lib - modules used by Perl 5 code
+
+== DESCRIPTION ==
+
+The 'lib' directory contains the Perl modules used by all the scripts written
+in Perl 5. This mostly means unit tests, Configure.pl, and developer tools.
+
+== SUBDIRECTORIES ==
+
+* File
+
+The File::Which module. A portable implementation of the which(1) shell utility.
+
+* IO
+
+The IO::CaptureOutput module. Captures output to STDOUT, STDERR, subprocesses,
+and XS.
+
+* Parrot
+
+Modules specific to Parrot. Includes modules such as Parrot::Test::More,
+Parrot::Config, Parrot::Headerizer, and more.
+
+* Perl
+
+The Perl::Critic::Policy::* modules. These modules are used by several tests
+to check that all source files follow the coding standard described in PDD07.
+
+* Pod
+
+Modules for parsing POD documentation such as Pod::Simple and Pod::Escapes.
+These are mostly used by the `html` make target to convert POD documentation
+to HTML.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
38 runtime/README
@@ -0,0 +1,38 @@
+== NAME ==
+
+runtime - runtime library for Parrot
+
+== DESCRIPTION ==
+
+The 'runtime' directory contains the runtime libraries and dynamic extensions
+used by HLL's.
+
+== SUBDIRECTORIES ==
+
+* parrot/bin
+
+Contains the Prove library: a PIR-based TAP harness.
+
+* parrot/dynext
+
+Contains the source files for dynamic extensions.
+
+* parrot/include
+
+Generated files containing constants and macros for use in PIR code. This
+directory is searched by default by the `.include` directive.
+
+* parrot/language
+
+Source files for Parrot::Compiler - a subclass of PCT::HLLCompiler - that's used
+for HLL interopability.
+
+* parrot/library
+
+Contains the files that serve as the Parrot runtime library. This directory is
+searched by default by the `.loadlib` directive.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
2  runtime/parrot/dynext/README
@@ -1,2 +0,0 @@
-
-This directory holds dynamic Parrot extension files.
View
10 runtime/parrot/include/README
@@ -1,10 +0,0 @@
-
-This directory contains mostly generated files:
-- include files with constants defined somewhere in the interpreter
- (see config/gen/parrot_include.pl for details)
-- configuration data (config.fpmc)
-- bytecode used at runtime (parrotlib.pbc)
-
-Additionally there are some snippets of PIR code:
-- hllmacros.pir provides some nifty PIR macros
-- test_more.pir provides boilerplate code for test scripts written in PIR
View
79 src/README
@@ -0,0 +1,79 @@
+== NAME ==
+
+src - source files used for Parrot internals
+
+== DESCRIPTION ==
+
+The 'src' directory contains the source files that make up the virtual machine
+and its various subsystems. It mostly contains C code, PMC definitions, and
+opcode definitions.
+
+== SUBDIRECTORIES ==
+
+* atomic
+
+Implementations of atomic operations on x86 and SPARC platforms.
+
+* call
+
+The Parrot Calling Conventions (PCC) for handling arguments and return values
+for subroutines.
+
+* dynoplibs
+
+Source files for creating dynamic opcode libraries that are loaded at runtime.
+
+* dynpmc
+
+Source files for creating dynamic PMC's that are loaded at runtime.
+
+* embed
+
+The Parrot embedding API. This is used for embedding a Parrot interpreter
+in third-party applications.
+
+* gc
+
+Source files that make up Parrot's garbage collection system and its public API.
+
+* interp
+
+Source files related to the interpreter such as callback handling, creation and
+destruction, compiler registration, etc.
+
+* io
+
+Parrot's IO subsystem and its public API.
+
+* nci
+
+The Native Call Interface for calling C code from PIR.
+
+* ops
+
+Core opcode definitions.
+
+* packfile
+
+Source files for processing packfiles: a PMC representation of Parrot bytecode.
+
+* platform
+
+Platform-dependent source files.
+
+* pmc
+
+Polymorphic Container (PMC) definitions.
+
+* runcore
+
+Source files that make up the runcore API.
+
+* string
+
+Parrot string subsystem.
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+
View
73 src/dynpmc/README.pod
@@ -1,73 +0,0 @@
-=pod
-
-=head1 OVERVIEW
-
-This is a build directory for custom PMCs with a sample foo.pmc
-providing the Foo PMC class.
-
-=head1 CREATING A DYNAMIC PMC
-
-=over 4
-
-=item 1
-
-Edit/create your foo.pmc source - For details on creating PMCs, see
-F<tools/dev/gen_class.pl>
-
-There are some differences you have to be aware of when creating dynamic PMCs.
-
-When declaring the dynamic PMC, you must specify the C<dynpmc> flag, as in:
-
- pmclass TclString extends TclObject dynpmc ... { ... }
-
-Note that regular (non-dynamic) PMCs have a type id
-C<enum_class_PMCNAME>, but dynamic PMCs obviously cannot use the same
-thing. Instead, a dynamically-chosen value is assigned at runtime -
-so, when you refer to the type of the class , you must dynamically
-determine the PMC type. So, while C<scalar> (a builtin) has the
-luxury of knowing at compile time what the class number of its child
-C<String> is -- for example:
-
- if (type == enum_class_String) { ...
-
-a dynamic PMC such as C<TclInt> must instead perform a runtime lookup
-of its corresponding C<TclString> PMC, resulting in the more complicated:
-
- static INTVAL dynpmc_TclString;
-
- pmclass TclInt extends TclObject extends Integer dynpmc group tcl_group {
-
- void class_init() {
- if (pass) {
- dynpmc_TclString = Parrot_PMC_typenum(interp,"TclString");
- }
- }
- }
-
-Finally, if you have a group of PMCs that are interdependent, use the
-C<group GROUPNAME> syntax to trigger a group library to be built. You
-will use the group name as the name of the library to load using the
-PASM op C<loadlib>.
-
- pmclass Match extends Hash dynpmc group match_group { ... }
-
-and then in your .pir or .pasm file:
-
- loadlib $P0, "match_group"
-
-=item 2
-
-Edit C<../../config/gen/makefiles/dynpmc.in> and append your PMC(s) to
-the build target. The dynpmc.in file is processed by Configure.pl to
-create the real makefiles. So, invoke the configure script, then make:
-
- $ perl Configure.pl
- $ make
-
-=item 3
-
-If anything changes inside parrot, be sure to:
-
- $ make dynpmc-clean
-
-=back
View
42 tools/README
@@ -0,0 +1,42 @@
+== NAME ==
+
+tools - development-related scripts and tools
+
+== DESCRIPTION ==
+
+The 'tools' directory contains the scripts and tools that are used during the
+build process and general Parrot development.
+
+== SUBDIRECTORIES ==
+
+* build
+
+Scripts, templates, and configuration files invoked by the default 'make'
+target. For example, the PMC to C compiler, opcode to C compiler, constant
+string support, etc.
+
+* dev
+
+Scripts for automating various tasks used by Parrot developers. For example,
+manipulating bytecode headers, generating test coverage reports, headerizer,
+etc.
+
+* docs
+
+Scripts related to documentation. For example, printing opcode summaries,
+generating HTML documentation, generating Latex documentation, etc.
+
+* install
+
+Scripts for checking that all things run in the 'install' directory and
+detecting missing parts.
+
+* release
+
+Scripts, templates, and configuration files invoked by the 'make install' and
+'make install-dev' targets. For example,
+
+== COPYRIGHT ==
+
+Copyright (C) 2011, Parrot Foundation.
+

Showing you all comments on commits in this comparison.

@leto
Owner

Markdown is preferable, since it renders nicely.

@cotto

A lot of things render nicely and POD would be more consistent.

@petdance
@leto
Owner

+1 to whatever, as long as it is pretty

@soh-cah-toa

Sorry, but I still think plaintext is best. README's (or any other IMPORTANT_FILE's for that matter) have always been traditionally in plaintext. It's not a website/wiki; they don't need Markdown. It's not a Perl module; they don't need POD. Even though GitHub can "render something nicely", there's simply nothing to render. It's just a few simple paragraphs that don't require any special formatting. Using a markup language for a tiny README file is serious overkill.

And as far as consistency, we only have a few README.pod's (which can be changed). Everything else is all plaintext. Clearly, those are the ones that are inconsistent.

@leto
Owner

-1 to plaintext README's . Beware of foolish consistency.

Nicely rendered README's improve the usability of our documentation and just plainly make them easier to read on the web. Case in point:

https://github.com/parrot/parrot/blob/master/t/README.pod

@jkeenan
Owner
@leto
Owner

@jkeenan: I don't know what email you are referencing, and trying to guilt people into using the mailing list by telling them where discussions "ought" to take place is not productive and condescending.

@soh-cah-toa

Damn, I guess it doesn't work without a file extension. I thought I might have a solution to the 'plaintext vs. markup' debate.

Something went wrong with that request. Please try again.