Pugs::Doc::Hack - How to hack on Pugs
# 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 $ sudo cpan Bundle::Pugs::SmokeKit # (once) $ make smoke # generates a smoke.html # Optionally, submit your smoke report to the public smokeserver: $ perl util/smokeserv/smokeserv-client.pl smoke.html
This document attempts to explain how to start working on Pugs, as well as conventions used in day-to-day development.
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 |-- misc Other modules, not directly used by Pugs |-- perl5 Internal Perl 5 modules for Pugs (compiler backends) |-- 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:
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 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
$ 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.
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.
pugs, i.e. the compiler/interpreter.
There is a util/perl6.vim Vim syntax file. There is an enhanced util/cperl-mode.el Emacs mode. If you don't use it, then original perl-mode works better than original cperl-mode.
Where applicable, conventions documented in Damian Conway's "Perl Best Practices" book (O'Reilly, 2005) should be followed by default. At the very least, all indenting should be done with spaces (4 per indent level) rather than tabs, so the code and documentation looks the same to everyone.
If you use Vim, you may want to set the following settings:
set shiftwidth=4 autoindent expandtab smarttab softtabstop=1
This will cause Vim to insert four spaces instead of a real tab upon pressing
<Tab>. The equivalent settings for Emacs are:
c-indentation-style: bsd c-basic-offset: 4 indent-tabs-mode: nil
If you use Emacs with the enhanced util/cperl-mode.el, you can set these code conventions in your config file with:
(add-hook 'cperl-mode-hook '(lambda () (cperl-set-style "Pugs")))
If you use BBEdit, you can configure it to auto-expand tabs like this:
Launch the BBEdit application.
In the 'BBEdit' (application) menu, choose 'Preferences'.
In the resulting dialog box, choose 'Editor Defaults' from the left col.
In the resulting panel, ensure 'Auto-Expand Tabs' is checked.
Also ensure the 'Default Font' is set to '4 spaces per tab'.
Close the dialog box.
These exact settings apply to BBEdit 8, the newest version; older versions of the program may store the same configuration options elsewhere.
See Pugs::Doc::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
You can also just say
./pugs -Iblib6/lib t/your/test/file.t.
Using the Parrot distribution, PGE can be tested interactively with
$ ./parrot compilers/pge/demo.pir
and with tests like those in t/p6rules/.
Using the PCRE distribution, PCRE can be tested interactively with
A cross index of standard Haskell libraries. It is searchable by type signature, name, etc.
Browsable Pugs VCS. You sometimes get a blank page the first time you access a URL (a timeout) - just click again.
Mirror of Pugs VCS head. Usually faster and more reliable than the OpenFoundry browser, but doesn't show diffs between revisions.
Pugs Smoke Reports Server. List of recently uploaded smoke reports sorted by the runcore used (normal Haskell backend, PIL2JS, PIL-Run, PIR, etc.), see util/smokeserv/README for more information.