Pugs::Doc::Hack - How to hack on Pugs
# Fetch latest Pugs from Subversion repository $ svn co http://svn.openfoundry.org/pugs $ cd pugs # review build options controlled by env variables $ $PAGER ./INSTALL # Configure Pugs $ perl Makefile.PL # Compile Pugs $ make # Test $ make test # or instead of Test, Smoke: # do the following only once $ sudo cpan Task::Smoke $ cp util/smoker-example.yml ~/.smoker.yml $ $EDITOR ~/.smoker.yml $ make smoke # generates smoke.html, smoke.yml # Optionally, submit your smoke report to the public smokeserver: $ perl util/smokeserv/smokeserv-client.pl smoke.html smoke.yml
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 general test suite, for all implementations |-- third-party Third party dependencies of Pugs, bundled for convenience `-- 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
Ideally, this is done after you add the file, but before you commit it. It can be run later if for some reason it's run initially.
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 not use any shebang line, as they specify a single runtime for the code but Perl 6 code should run under multiple runtimes, Pugs and the v6 Perl 5 module to name two. 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.
Follow the link titled "(history of this directory)" to see an SVN log excerpt. It will list all changes from that directory and its subdirectories only.
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.