=head1 NAME

pugs::hack - How to hack on Pugs

=head1 SYNOPSIS

    # Fetch latest Pugs from Subversion repository
    $ svn co http://svn.openfoundry.org/pugs
    $ cd pugs

    # Configure Pugs
    $ perl Makefile.PL

    # Compile Pugs
    $ make

    # Test
    $ make test       # or
    $ make smoke      # generates a smoke.html

=head1 DESCRIPTION

This document attempts to explain how to start working on Pugs, as well as
conventions used in day-to-day development.

=head2 Source tree map

The Pugs source tree includes several major sections:

    .
    |-- LICENSE      Licenses that apply to the Pugs distribution
    |-- debian       Packaging rules for dpkg-based systems
    |-- docs         Documentation relating to Pugs/Perl 6/Haskell
    |-- examples     Examples of Perl 6 usage; many work in Pugs today
    |-- ext          Perl 6 modules that are installed with Pugs
    |-- inc          Perl 5 modules needed for build/test/install
    |-- lib          Perl 5 modules that are installed with Pugs
    |-- modules      Perl 6 modules not working today; -> FreePAN
    |-- perl5        Perl 5 modules not installed with Pugs
    |-- script       pugscc, the Pugs Compiler Collection
    |-- src          Source code for Pugs itself
    |-- t            Perl 6 test suite
    |-- t_disabled   Temporarily disabled tests
    `-- util         Utilities for hacking and testing Pugs

Expanding this one level deeper:

    .
    |-- LICENSE            Licenses that apply to the Pugs distribution
    |
    |-- debian             Packaging rules for dpkg-based systems
    |
    |-- docs               Documentation relating to Pugs/Perl 6/Haskell
    |   |-- AES                Drafts of Perl6::Bible chapters
    |   |-- class              Object system sketches (XXXX: out of date?)
    |   |-- notes              Misc design notes and musings
    |   |-- other              Misc tips to day-to-day development
    |   |-- quickref           Perl 6 quick reference pages
    |   |-- src                Junction implementation sketch (XXXX: ood?)
    |   |-- talks              Slides for Pugs and Perl 6 talks
    |   |-- zh-cn              Simplified Chinese doc translations
    |   `-- zh-tw              Traditional Chinese doc translations
    |
    |-- examples           Examples of Perl 6 usage; many work in Pugs today
    |   |-- advocacy           Pugs/Perl 6-advocacy MOTD generator
    |   |-- algorithms         Basic algorithms
    |   |-- cgi                CGI scripts and applications
    |   |-- continuation       Fun with continuations
    |   |-- cookbook           Perl 6 idiomatic Perl Cookbook
    |   |-- functional         Functional programming concepts
    |   |-- games              Playable games
    |   |-- golf               Minimal (key)stroke puzzle solutions
    |   |-- hashes             Use of Perl 6 hashes
    |   |-- japh               JAPHs using various idioms
    |   |-- junctions          Fun with junctions
    |   |-- naive_bayesian     Naive Bayesian Text Classification
    |   |-- nested_loops       Many ways to do runtime nested loops
    |   |-- network            Networking clients, servers, bots, etc.
    |   |-- obfu               Obfuscated code and obfuscation techniques
    |   |-- output             Expected example outputs, for testing
    |   |-- p6explain          Incomplete tool which explains Perl 6 constructs
    |   |-- perl5              Programs that use Perl 5 modules
    |   |-- poetry             Perl 6 poetry
    |   |-- ppt                Perl 6 Power Tools, ports of *nix userland
    |   |-- qotw               Perl 6 solutions to plover's Quiz Of The Week
    |   |-- slurpy-list-parms  Use of Perl 6 slurpy lists (XXXX: -> t/?)
    |   |-- tutorial_gen       Tutorial generator (XXXX: huh?)
    |   `-- vmethods           Add virtual methods to existing types
    |
    |-- ext                Perl 6 modules that are installed with Pugs
    |   |-- Algorithm-TokenBucket  Token bucket rate limiting
    |   |-- Benchmark          Benchmark runtime of Perl 6 code
    |   |-- CGI                CGI author's helper module
    |   |-- Config-Tiny        Pre-Pugs-OO .ini file reader
    |   |-- Date               Date and time modules
    |   |-- DateTime           Port of Perl 5 DateTime, with API changes
    |   |-- DateTime-Set       Port of Perl 5 DateTime::Set/Span/SpanSet
    |   |-- File-Find          Traverse a directory tree
    |   |-- File-Spec          Portable File handling
    |   |-- FindBin            Find directory of Perl script
    |   |-- HTML-Entities      Encode/decode HTML entities
    |   |-- HTTP-Server-Simple Base class for simple CGI-capable HTTP servers
    |   |-- Kwid-Event-Parser  Event-based API (like XML SAX) for Kwid
    |   |-- Locale-KeyedText   Refer to UI strings by key
    |   |-- Module-Pluggable-Fast  Find and load plugin modules
    |   |-- Net-IRC            IRC protocol implementation
    |   |-- Perl-Compiler      A Perl 6 port of Pugs
    |   |-- Perl-MetaModel     Sketch of Perl 6 Object Meta Model
    |   |-- Perldoc            Event-based API for Perldoc DOM
    |   |-- Pod-Event-Parser   Event-based API (like XML SAX) for POD
    |   |-- Set                Set calculus operations
    |   |-- Set-Infinite       Infinite set and recurrence operations
    |   |-- Span               Span operations
    |   |-- Test               Testing support library
    |   |-- Test-Builder       Backend for building test libraries
    |   |-- Text-Glob          Translate glob to regex
    |   |-- Tree               Basic n-ary tree data structure
    |   |-- URI                Escape/unescape URI strings
    |   |-- WTemplate          Widget-based templating engine
    |   |-- Perl-Compiler      A Perl 6 compiler written in Perl 6
    |   |-- fp                 Functional programming operators
    |   |-- lib                Pragma to add paths to @*INC
    |   `-- libwww-perl        Port of Perl 5 libwww-perl modules
    |
    |-- inc                Perl 5 modules needed for build/test/install
    |   |-- Module             Module::Install
    |   `-- Test               Test::Harness
    |
    |-- lib                Pugs- and Perl 6-related Perl 5 modules
    |   |-- Code-Perl          An AST to Perl 5 code generator
    |   |-- Inline             Inline::Pugs
    |   |-- P5-PIL-Run         PIL evaluator in Perl 5
    |   |-- Perl6              Perl6::MakeMaker, Perl6::Pugs
    |   |-- Perl6-MetaModel    Perl6's OO metamodel, in Perl 5
    |   `-- pugs               POD docs for Pugs itself
    |
    |-- modules            Perl 6 modules not working today; -> FreePAN
    |   |-- Class-Events       XXXX: It should not be here
    |   |-- Grammars           XXXX: It should not be here
    |   |-- POE                Beginning of an experimental port of Perl 5 POE
    |   `-- Sample-Module      Sample module for Perl 6 authors
    |
    |-- perl5              Perl 5 modules not installed with Pugs
    |   |-- Code-Perl          Helper module for Perl 5 code generation
    |   |-- PIL-Run            PIL virtual machine in Perl 5
    |   `-- Perl6-MetaModel    Perl 5 Prototype of the Perl 6 Metaclass model
    |
    |-- script             pugscc, the Pugs Compiler Collection
    |
    |-- src                Haskell source for pugs itself
    |   |-- Data               Syck-based YAML parser
    |   |-- Emit               Parrot PIR backend
    |   |-- IMC                Parrot IMC backend
    |   |-- Pugs               Core Pugs engine
    |   |-- RRegex             PCRE-based regular expressions support
    |   |-- pcre               Import of PCRE source
    |   |-- perl5              Perl 5 bidirectional call support
    |   |-- perl6              The Perl 6 prelude (definition of builtins)
    |   |-- pge                Import of PGE (Parrot Grammer Engine) source
    |   `-- syck               Import of Syck source
    |
    |-- t                  Pugs/Perl 6 test library
    |   |-- 01-sanity          Sanity checks that testing can proceed
    |   |-- builtins           Builtin function tests
    |   |-- data_types         Basic data type tests
    |   |-- examples           Make examples/ tree act as tests
    |   |-- general            Miscellaneous tests
    |   |-- junction           Junction tests
    |   |-- macros             Macro tests
    |   |-- magicals           Magical variable tests
    |   |-- oo                 Object Oriented programming tests
    |   |-- operators          Operator tests
    |   |-- packages           Tests for packages
    |   |-- pugsbugs           Uncategorized tests for known broken behavior
    |   |-- pugsrun            Tests for pugs (as opposed to Perl 6)
    |   |-- rules              Perl 6 rule and Perl 5 regex tests
    |   |-- statements         Statement-level construct tests
    |   |-- subroutines        Block/Code/Sub/etc. tests
    |   |-- syntax             Basic syntax tests
    |   |-- unspecced          Tests for Pugs extensions to Perl 6
    |   |-- var                Variable declaration tests
    |   |-- Synopsis           Pointers to online AES docs and tests
    |   `-- Test-Less          Test index for test-less utility
    |
    |-- t_disabled         Disabled tests
    |   |-- Dialects           Perl 6 non-standard dialects
    |   `-- rules              Port of tests from CPAN module Perl6::Rules
    |
    `-- util               Utilities for hacking and testing Pugs
        `-- livecd             Tool to create a minimalistic Pugs Live CD

=head2 Subversion properties

If you add a new text file (e.g. a test, a C<.pm>, etc.) to the repository,
please use C<util/add-svn-props.sh> to add standard Subversion properties to
your new file:

    $ ./util/add-svn-props.sh newfile1 newfile2

If you're on Win32 and can't run shell scripts, run C<svn> manually:

    $ svn propset svn:eol-style "native" newfile1 newfile2
    $ svn propset svn:mime-type "text/plain; charset=UTF-8" newfile1 newfile2

If you create a new subdirectory under C<ext/>, please remember to set the
C<svn:ignore> property to tell Subversion to ignore automatically generated
files like C<Makefile> or C<blib/>.

    $ cat > /tmp/props
    pm_to_blib
    blibdirs
    Makefile
    Makefile.old
    blib
    $ svn propset svn:ignore -F /tmp/props ext/Your-New-Module

Except for the files in F<script/> and F<util/>, C<svn:executable> should
always be unset, even for test files.

=head2 Shebang lines

All test files should use C<#!/usr/bin/pugs> as the shebang line (first line of
the script). There're no real technical reasons for this convention, it's just
for consistency. Remember to put a C<use v6> in the beginning of your Perl 6
programs, too, to keep perl5 from accidentally running Perl 6 code.

=head2 Naming conventions

=over

=item *

"Perl 6" is the name of the programming language and the project, while "perl6"
is the name of the Perl 6 compiler/interpreter.

=item *

"Pugs" is the name of the Pugs project, while "pugs" is the name of the binary
C<pugs>, i.e. the compiler/interpreter.

=item *

"Perl 5" is the name of the programming language and the project, while "perl5"
is the name of the Perl 5 interpreter.

=back

=head2 Resources

=over

=item *

L<http://www-users.cs.york.ac.uk/~ndm/hoogle/> A cross index of
standard Haskell libraries. It is searchable by type signature, name,
etc.

=back
