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.htmlDESCRIPTION
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 PugsExpanding 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 CDSubversion 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 newfile2If 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 newfile2If 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-ModuleExcept 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.
Resources
http://www-users.cs.york.ac.uk/~ndm/hoogle/ A cross index of standard Haskell libraries. It is searchable by type signature, name, etc.