root/INSTALL

Note: To build v6-alpha, see the INSTALL.v6-alpha file instead.

INSTALLING PUGS VIA CABAL
-------------------------

The current recommended way to build Pugs is via cabal-install.

Follow these steps:

1. Make sure you have Cabal, HTTP, zlib and cabal-install installed
   (in this order):

    http://hackage.haskell.org/cgi-bin/hackage-scripts/package/Cabal
    http://hackage.haskell.org/cgi-bin/hackage-scripts/package/HTTP
    http://hackage.haskell.org/cgi-bin/hackage-scripts/package/zlib
    http://hackage.haskell.org/cgi-bin/hackage-scripts/package/cabal-install

If you're unsure how to install this, the instructions contained in the README
file of Cabal will help you get started. Those instructions work for all the
above packages.

2. Type the following commands:

    cabal update
    cabal install Pugs

...and you're done.  To build an optimized Pugs for benchmarking or smoke
testing, replace the second command with:

    cabal install -O2 Pugs

3. To upgrade the current Pugs installation to the latest released version,
   simply type the same two lines of commands above:

    cabal update
    cabal install Pugs

INSTALLING PUGS ON CYGWIN
-------------------------
For installing pugs on cygwin via cabal, please follow these instructions:
http://use.perl.org/~rurban/journal/36897



---8<------8<------8<------8<------8<------8<------8<------8<------8<------8<---
                   Cut here - Instructions below are outdated!
---8<------8<------8<------8<------8<------8<------8<------8<------8<------8<---


BUILDING PUGS
-------------

Pugs needs the Glasgow Haskell Compiler (GHC), version 6.8.2 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. (Several hours)

Additionally, Pugs uses the Cabal framework (http://haskell.org/cabal/),
which is usually bundled with GHC itself. (The 6.6.1 source code contains it.)

http://jnthn.net/perl6/ has binary builds for Win32.  For Mac OS X (PowerPC),
http://www.unobe.com/packages/ has binary builds too. If you'd like to build
Pugs by hand, http://wiki.kn.vutbr.cz/mj/?Perl%206%20and%20Parrot has some
instructions.

Debian Etch's (stable as of 2007) version of GHC is too old to compile pugs,
see the section below on compiling the version from testing.  GHC 6.6.1 debs
for etch are available (not apt-gettable):
i386 http://feather.perl6.nl/~diakopter/
amd64 http://airen.bcm.umontreal.ca/ghc-pugs-etch/

Do not use ActivePerl on OS X to run Makefile.PL.  ActivePerl is built as a
Universal binary, and the pugs build system will try to use build
information from ActivePerl and cause the build to fail.  The Perl from
MacPorts (http://www.macports.org/) seems to work well.

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

During the build process, the script will try to install HsJudy (a Haskell binding to the Judy array library written in C). If you don't have Judy installed, this step might fail, so you should install Judy. Most distros include that library.

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="parrot noperl5" (bash)
    setenv PUGS_EMBED "parrot noperl5" (csh)

Perl5 is now embedded by default.  Use "noperl5" to disable.

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)

The HARNESS_PUGS environment may come to handy once you want to limit
CPU and RAM usage of your smoking (*NIX only):

    HARNESS_PUGS=util/limited_pugs make smoke

Modify util/limited_pugs in your local copy if it doesn't fit your needs.

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 soon

To run the test suite with a pretty HTML matrix showing test results:

    make smoke

(See also the HARNESS_PUGS environment in the previous section.)

To turn on profiling in the GHC compiler:

    make prof

To hack on Pugs using the GHC interactive shell:

    make ghci

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.


COMPILING GHC ON DEBIAN ETCH
----------------------------

Note (Aug 2008): Pugs requires ghc 6.8 now.  Lenny has this, but you can't
reasonably build it on Etch - it build-deps Lenny's gcc, which build-deps
Lenny's dpkg...  Just install the binary package from http://www.haskell.org/ghc/

This is a somewhat tricky procedure at present, because installing a new ghc may
make old libghc6-* packages uninstallable.  The following procedure should work
around that, but be warned it hasn't been tested in exactly this way.  Complain
on #perl6 if you have trouble.  Thanks to moritz++, Aankhen``++, and diakopter++
for helping to figure this out. -rhr

1. Compile the new version of GHC from testing:
    echo 'deb-src ftp://ftp.debian.org/debian/ lenny main contrib non-free' >> /etc/apt/sources.list
    apt-get update
    apt-get build-dep ghc6
    apt-get source --compile ghc6
    Don't install the debs yet!
2. Remove old GHC packages
    dpkg --get-selections|grep ghc
    Check to see what you'll need to reinstall later
    apt-get remove haddock
    dpkg --get-selections|grep ghc|awk '$2 == "install" {print $1}'|xargs apt-get remove
    dpkg --get-selections|grep libghc
    Make sure no libghc6-* packages are installed
3. Install new GHC
    dpkg -i ghc6_6.6.1-*.deb
    This may give a warning about not deleting /usr/lib/ghc-6.6, that seems to be harmless
4. Satisfy build-deps for GHC libs
    apt-get build-dep haddock
    apt-get source --compile haddock
    dpkg -i haddock*.deb
    apt-get build-dep haskell-utils
    apt-get source --compile haskell-utils
    dpkg -i haskell-utils*.deb
    dpkg -i ghc6-doc_6.6.1-*.deb
    dpkg -i ghc6-prof_6.6.1-*.deb
    apt-get build-dep libghc6-mtl-dev libghc6-network-dev libghc6-time-dev
5. Build and install GHC libs
    apt-get source --compile libghc6-mtl-dev
    dpkg -i libghc6-mtl-dev*.deb
    apt-get source --compile libghc6-network-dev
    dpkg -i libghc6-network-dev*.deb
    apt-get source --compile libghc6-time-dev
    dpkg -i libghc6-time-dev*.deb


NOTES FOR GHC 6.6.1 AND REVISION > 19955
----------------------------------------

This is only a way to get a running pugs with ghc 6.6.1 during the
migration phase to ghc 6.8.x. It does *NOT* solve any issues. It is tested
with the  following environment (I believe only the ghc part is essential for
this workaround):

- GNU/Linux 2.6.22-14
- libc6 2.6.1-1ubuntu10
- gcc-Version 4.1.3 20070929 (prerelease) (Ubuntu 4.1.2-16ubuntu2)
- perl 5.8.8
- Cabal-1.1.6.2, base-2.1.1, filepath-1.0, (ghc-6.6.1),
  haskell98-1.0, mtl-1.0.1, network-2.0.1, parsec-2.0, readline-1.0,
  regex-base-0.72, regex-compat-0.71, regex-posix-0.71, rts-1.0,
  stm-2.0, template-haskell-2.1, time-1.1.1, unix-2.1

The last revision that builds directly from repository on this environment
was r19955.

1. Update to current version
  svn update .

2. Revert some files to former version
  svn update -r19955 src/Pugs/Meta/Str.hs src/Pugs/Types.hs src/UTF8.hs \
            Pugs.cabal.in util/build_pugs.pl third_party/ \
            src/Pugs/Compile/Pugs.hs src/Pugs/Eval.hs

3. Build it ...
  perl Makefile.PL && make

4. ..possibly twice, if it failed
  make

5. Skip building Test.pm.yml
  cp ext/Test/lib/Test.pm blib6/lib/

Last two steps seems sometimes to be necessary to avoid messages like this
  ./pugs -CParse-YAML ext/Test/lib/Test.pm > blib6/lib/Test.pm.yml
  pugs: user error (Not implemented: asYAML "Sub")