=====================================================================
|        ______                                                     |
|      /\   __ \                                                    |
|      \ \  \/\ \ __  __  ______  ______     (P)erl6                |
|       \ \   __//\ \/\ \/\  __ \/\  ___\    (U)ser's               |
|        \ \  \/ \ \ \_\ \ \ \/\ \ \___  \   (G)olfing              |
|         \ \__\  \ \____/\ \____ \/\_____\  (S)ystem               |
|          \/__/   \/___/  \/___/\ \/____/                          |
|                            /\____/                                |
|                            \/___/                                 |
|                                                                   |
=====================================================================

Pugs is Copyright 2005 by Autrijus Tang.  All Rights Reserved.

The "PGE" subsystem is derived from PGE by Patrick Michaud,
under the Perl license.  See src/pge/README.

The "PCRE" subsystem is derived from PCRE 5.0 by Philip Hazel,
under a BSD-style license.  See src/pcre/LICENCE.

The "Syck" subsystem is derived from Syck 0.55 by "why the lucky stiff",
under a BSD-style license.  See src/syck/COPYING.

The "Rule" subsystem is derived from Parsec 2.0 by Daan Leijen,
under a BSD-style license.  See src/Pugs/Rule/LICENSE.

The "RRegex" subsystem is derived from hsregex 0.2 by John Meacham,
under a BSD-style license.  See src/RRegex/LICENSE.

The "UTF8" subsystem is derived from Sven Moritz Hallberg's work,
under a BSD-style license.  See src/UTF8.lhs.

The "Unicode" subsystem is derived from Dimitry Golubovsky's work,
under the same license as GHC.  See LICENSES/GHC.

LICENSE INFORMATION
-------------------

This code is free software; you can redistribute it and/or modify it under
the terms of either:

    a) the GNU General Public License, version 2, or
    b) the Artistic License, version 2.0beta5.

Please see the "GPL-2" and "Artistic-2" files under the "LICENSE" directory
for the full license text.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either
the GNU General Public License or the Artistic License for more details.

INSTALLATION
------------

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.2.0 or above to support Perl 6 Rules.  To install Parrot,
follow the instructions at http://www.parrotcode.org/.

http://www.jwcs.net/~jonathan/perl6/ has binary builds for Win32.  If you'd
like to build by hand, http://wiki.kn.vutbr.cz/mj/?Perl%206%20and%20Parrot has
instructions (and binaries, too).

For dynamic loading/inlining of Haskell modules, you should install the
hs-plugin library, available here:

    ftp://ftp.cse.unsw.edu.au/pub/users/dons/hs-plugins/snapshots/

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

Optionally 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)

CAVEATS FOR GCC 4.0 USERS
-------------------------

Mac OS X 10.4 "Tiger" users may see this error message when compiling Pugs:

    ___DISCARD__
    collect2: ld returned 1 exit status

Until GHC 6.4.1 is released, you need to need to issue this command first:

    sudo gcc_select 3.3

Then recompiling Pugs using a clean tree.  Other users of GCC 4.0 systems
may also need to switch to use GCC 3.3 to compile Pugs at this moment.

CAVEATS FOR x86_64 MACHINES
---------------------------

Until GHC 6.4.1 is released, users with x86_64 (64 bit Athlon) CPU's should
consider using a development snapshot of GHC.  GHC 6.4 had bugs on x86_64
which break garbage collection and rules (regexps).  These bugs were fixed
in GHC CVS by around 11-May.  There are hints on using snapshots at the end
of this section.

Here are the known problems:

(1) GHC 6.4 has a garbage collector bug on x86_64 (64 bit Athlon) machines;
users may see crashes complaining about "strange objects".

Until GHC 6.4.1 is released, a partial workaround is to avoid GC by
requesting a large heap, using either command line arguments:

    ./pugs +RTS -A200M -RTS

or an environment variable:

    GHCRTS='-A200M'

These request a 200 MB heap, which is sufficient to run most programs.

Running all tests unfortunately requires a lot more memory (perhaps 1000M).
A possible alternative, which someone could explore and report on, would be
to try using a 32-bit GHC instead.

(2) Rules (regexps) may not work with GHC 6.4 on x86_64.  Users may see
"internal error: adjustor creation not supported on this platform".
There is no known workaround.  This bug has been fixed in current
development snapshots.

Hints on using a development snapshot of GHC:

Note that this will take a long time, and it may not work.

First, check if a sufficiently recent "Stable" source snapshot is available
(as of 15-May, there isn't one yet).  If not, you might try a "HEAD" snapshot
(it is not clear anyone has actually tried this).  Otherwise, use might use
cvs to grab your own snapshot:

    CVSROOT=:pserver:anoncvs@glass.cse.ogi.edu:/cvs; export CVSROOT
    cvs login     # passord cvs
    cvs checkout fpconfig
    cd fptools
    cvs checkout ghc hslibs libraries happy alex

    autoreconf
    ./configure
    make
    make install

There are no guarantees with a CVS snapshot.  It may not even compile.


MAILING LISTS
-------------

The mailing list for Pugs is perl6-compiler.  Subscribe by sending mail to
<perl6-compiler-subscribe@perl.org>.  Mailing list archive is availabe at:

    http://nntp.perl.org/group/perl.perl6.compiler          (HTTP)
    http://groups-beta.google.com/group/perl.perl6.compiler (HTTP)
    nntp://nntp.perl.org/perl.perl6.compiler                (NNTP)

Please submit bug reports to <pugsbugs@perl.org>.

WEB SITES
---------

The Pugs homepage is at:

    http://pugscode.org/

For Perl 6 related information, please see:

    http://dev.perl.org/perl6/

Enjoy,
/Autrijus/