Questions we ought to be able to answer

[Kevin Polulak]

On Sat, Jul 16, 2011 at 10:28 PM, James E Keenan <jkeen at verizon.net> wrote:

>
> 8. What are the purposes of the top-level directories in the Parrot
> distribution? Would they each benefit from short READMEs explaining that?
>

I'm still not completely sure about the purpose of all the top-level
directories but here's what I've been able to gather:

   - *blib* - Short for "binary library". Contains the libparrot static and
   dynamic libraries. Also includes a pretty printer Python script for GDB
   (which I think doesn't belong here anyway).
   - *compilers* - Contains the source files for several compilers:
   data_json, imcc, opsc, pct, pge, and tge.
      - *data_json* - Generates a JSON representation of a PMC.
      - *imcc* - "Intermediate Code Compiler". The compiler used for
      converting PIR source code into Parrot bytecode.
      - *opsc* - The opcode compiler. Converts opcode definition files into
      C source code.
      - *pct* - The compiler used by the "Parrot Compiler Tools".
      - *pge* - "Parrot Grammar Engine". An implementation of Perl 6 regex's
      designed for PCT.
      - *tge* - "Tree Grammar Engine". A tool for transforming trees known
      as Parrot Abstract Syntax Tree (PAST).
   - *config* - Source files (mostly Perl 5 modules) used by Configure.pl
   during the configuration process.
   - *docs* - General documentation in POD format. Useful for Parrot
   developers, users, and compiler developers. Also contains the "Parrot
   Developer's Guide: PIR" and Parrot Design Documents (PDDS) that describe
   some of the internals of the virtual machine.
   - *editor* - Plugins and scripts for several popular editors including
   vim, emacs, and kate. Examples include syntax highlighting, automatic
   indenting, and tags generation.
   - *examples* - Example source files (mostly PIR) demonstrating common
   tasks such as NCI, SDL, PASM, and a PIR tutorial. Also includes the source
   files for the demo languages "abc" and "Squaak".
   - *ext* - Short for "extensions". Includes nqp-rx, winxed, and the
   embedding interface for Perl 5.
   - *frontend* - Contains the Parrot frontend and other frontend programs
   including a bytecode disassembler, merger, dumper, and a debugger (HBDB
   coming soon).
   - *include* - C header files used by the core VM and IMCC.
   - *lib* - Short for "library". Contains several Perl 5 modules such as
   the test suite, a "POD to HTML" converter, and Headerzier for generating C
   function declarations.
   - *ports* - Contains OS specific files for building packages for Cygwin,
   Debian, Fedora, Mac OS X, Mandriva, openSUSE, and Ubuntu (I'm not 100% sure
   about this directory).
   - *runtime* - Contains the source files (mostly PIR and PASM) that make
   up the Parrot runtime library. Also includes dynamic extensions.
   - *src* - Contains the C source files that make up the internals of the
   virtual machine.
   - *t* - Parrot test suite. Most of them are PIR files but tests that must
   be run before the VM is built are written in Perl 5. Utilizes the Test
   Anything Protocol (TAP).
   - *tools* - Utilities (all in Perl 5) used mostly by the developers but
   also users of PCT. Examples include Makefile generation, release automation,
   sending Smolder reports, and creating files for new languages.

Yes, I do think we could benefit from including a small README file in each
top-level directory. More documentation is always a good thing. I opened up
an RFC in TT #2155 <http://trac.parrot.org/parrot/ticket/2155> for this.

-- 
- Kevin Polulak (soh_cah_toa)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.parrot.org/pipermail/parrot-dev/attachments/20110717/6aaa8a7a/attachment.html>