The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Perl6-Pugs-6.2.9
River stage zero No dependents
++
/ pugs::hack

NAME

pugs::hack - How to hack on Pugs

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

DESCRIPTION

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

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
    |   |-- 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
    |   |-- MIME-Base64        Base64 encode/decode (not a Perl 5 port)
    |   |-- Module-Pluggable-Fast  Find and load plugin modules
    |   |-- Net-IRC            IRC protocol implementation
    |   |-- Perl-Compiler      A Perl 6 port of Pugs
    |   |-- Perldoc            Event-based API for Perldoc DOM
    |   |-- Pod-Event-Parser   Event-based API (like XML SAX) for POD
    |   |-- Recurrence         Recurrence operations
    |   |-- Set                Set calculus operations
    |   |-- Set-Infinite       Infinite set 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
    |   |-- 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
    |   |-- PugsBuild          Support modules for config.yml make controls
    |   `-- Test               Test::Harness
    |
    |-- lib                Pugs- and Perl 6-related Perl 5 modules
    |   |-- Inline             Inline::Pugs
    |   |-- Perl6              Perl6::MakeMaker, Perl6::Pugs
    |   `-- pugs               POD docs for Pugs itself
    |
    |-- modules            Perl 6 modules not working today; -> FreePAN
    |   |-- Class-Events       Redesign of Perl 5's Class::Publisher
    |   |-- Date               Date/calendar calculations
    |   |-- Grammars           Perl 6 grammer written as Perl 6 rules
    |   |-- POE                Beginning of an experimental port of Perl 5 POE
    |   |-- Perl-MetaModel     Sketch of Perl 6 Object Meta Model
    |   `-- 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
    |   |-- PIL2JS             PIL to JavaScript compiler
    |   |-- Perl6-MetaModel    Prototype Perl 6 metaclass model: Perl 5
    |   |-- Perl6.MetaModel    Prototype Perl 6 metaclass model: JS
    |   |-- T2-Perl6           T2 (Tangram::Schema redesign) -> Perl6::Class 
    |   `-- org.perl6.metamodel  Prototype Perl 6 metaclass model: Java
    |
    |-- 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
    |   |-- builtins           Problems with system() and strings with spaces
    |   `-- 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

Subversion properties

If you add a new text file (e.g. a test, a .pm, etc.) to the repository, please use 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 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 ext/, please remember to set the svn:ignore property to tell Subversion to ignore automatically generated files like Makefile or 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 script/ and util/, svn:executable should always be unset, even for test files.

Shebang lines

All test files should use #!/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 use v6 in the beginning of your Perl 6 programs, too, to keep perl5 from accidentally running Perl 6 code.

Naming conventions

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

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

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

Testing

See pugs::run and t/README. If you wish to use the prove utility to run individual tests or test directories, you will need to set at least the following environment variables first:

    $ export HARNESS_PERL=./pugs
    $ export PERL6LIB=blib6/lib

Resources