BUILDING PUGS
-------------
Pugs needs the Glasgow Haskell Compiler (GHC) 6.4 or above. To install GHC,
download a binary build from http://haskell.org/ghc/. Although source code
for GHC is available, it will take a very long time to build by yourself.
Pugs needs Parrot 0.4.1 or above to support Perl 6 Rules and PIR evaluation.
To install Parrot, follow the instructions at http://www.parrotcode.org/.
http://www.jwcs.net/~jonathan/perl6/ and http://pxperl.com/ both have
binary builds for Win32. If you'd like to build Pugs by hand,
http://wiki.kn.vutbr.cz/mj/?Perl%206%20and%20Parrot has some instructions.
For dynamic loading/inlining of Haskell modules, you should install the
hs-plugin library, available here:
http://www.cse.unsw.edu.au/~dons/code/hs-plugins
To install Pugs on your system, simply type this in the command line:
cpansign -v # optional; see SIGNATURE for details
perl Makefile.PL
make # or 'nmake' on Win32
make test
make install
Both make and make test can take a long time (perhaps hours).
To change the installation location, pass PREFIX=/opt/wherever to
Makefile.PL like so:
perl Makefile.PL PREFIX=/your/prefix/here
XXX NOTE!!!!!!!!
PREFIX doesn't actually work right now. So ignore what I just said. But if
it did work, that's how you would do it.
Do not set PREFIX to your Perl 5 installation dir, as that would overwrite
some of the files there with their Pugs counterparts.
ENVIRONMENT VARIABLES
---------------------
There are several environment variables that control pugs's build process.
You may use the GHC environment variable to set the ghc executable before
you run "perl Makefile.PL", for example:
export GHC=${HOME}/bin/ghc (bash)
setenv GHC ${HOME}/bin/ghc (csh)
To control which optional subsystems are embedded in Pugs, set the
PUGS_EMBED variable. For example:
export PUGS_EMBED="perl5 parrot" (bash)
setenv PUGS_EMBED "perl5 parrot" (csh)
XXX Note!
Using embedded parrot is currently NOT recommended on win32 and x86_64.
To build with an embedded parrot interpreter, make sure the PUGS_EMBED
variable contains "parrot", and set the PARROT_PATH variable to point to
the directory in which you checked out the parrot source tree. For example:
export PARROT_PATH=${HOME}/src/parrot (bash)
setenv PARROT_PATH ${HOME}/src/parrot (csh)
MAKE TARGETS
------------
The default make target builds an optimized Pugs. This means that Pugs will
be slower to compile, but will run much faster. To disable this, run:
make unoptimized # unoptimised will work, too. We're not picky.
To run the test suite:
make test
To make a pretty HTML matrix showing test results:
make smoke
To run the test suite using the PIR backend:
make pirtest
To make a pretty HTML matrix showing test results using the PIR backend:
make pirsmoke
To turn on profiling in the GHC compiler:
make profiled
BUILD CONFIGURATION CONSOLIDATION VIA config.yml
------------------------------------------------
To keep the multitude of configuration options and mechanisms under
control for the build, we're moving over some of the above to a
centralized file, "config.yml" under the build root. This file is in
YAML format[1]; if it does not exist, one with defaults will be created
for you.
The options you can control there include:
- optimization level: whether `make` means `make optimized` or
`make unoptimized` by default.
- precompilation options: by default, pugs is built with the Standard Prelude
compiled into it. This makes many Perl 6 builtins available to pugs, and
loads fast. You can specify additional modules to inline a precompiled
version of into the executable: Test.pm is a good choice if running the
test suite. The cost of this is a longer build process which requires much
more RAM.
- GHC heap size: if precompiling modules other than Prelude.pm into pugs, you
will probably need to increase the amount of RAM GHC permits itself to use,
otherwise it will abort the build. And if your machine is low on RAM, and
itself runs out of memory while building pugs, you can set this to a low
value (but turn off optimization and precompilation too).
- install_dir: if set, `make install` will put everything under this
directory. Do not set this to your Perl 5 installation, since that
will overwrite some of the files there with the Pugs counterparts
(as will make install PREFIX= as noted above.)
You can override values set in this file temporarily via the single
PUGS_BUILD_OPTS environment variable. For example, if you normally do
precompile Prelude.pm but want a faster build just this once:
env PUGS_BUILD_OPTS=precompile_prelude=false make
See `util/config-template.yml` for more information.
[1] See <http://yaml.org/>. Only a subset of the YAML syntax is permitted
at the moment, to avoid a dependency on the full parser.
CAVEATS FOR ALL USERS
---------------------
Parrot is used to provide Perl6-style regular expressions.
Perl5-style regular expressions (eg, rx:perl5/foo/) can be used
without any parrot at all. Pugs can be built to use parrot external
(the default), or embedded. External is recommended.
Embedding parrot currently requires a parrot version 0.4.1 or later.
Recent copies of parrot can be obtained from
http://www.parrotcode.org/source.html .
CAVEATS FOR Win32 USERS
-------------------------
Embedding Perl5 is disabled GHC is built with MinGW/GCC and Perl
is usually built with VC++, they cannot embed one another.
CAVEATS FOR GCC 4.0 USERS
-------------------------
GHC 6.4.1 or later is required.
This applies to Mac OS X 10.4 "Tiger", and all other GCC 4.0 systems.
CAVEATS FOR x86_64 MACHINES
---------------------------
GHC 6.4.1 or later is required.