mercury/README.Cygwin

-----------------------------------------------------------------------------

INTRODUCTION

Mercury has been ported to Windows using the "Cygwin"
(formerly also known as "Cygwin32" and "gnu-win32") Unix emulation
package.  We have tested the port on the following versions of Windows:

    * Windows XP SP3
    * Windows 7
    * Windows Server 2008 R2

It should also work with Windows XP SP2 and Windows Vista but we have not
tested it with those.

In the past Mercury worked with Windows, 95, 98, ME, 2000 and NT but we no
longer actively maintain support for those versions.

This file documents how to install the binary distribution of
Mercury on Windows and how to build the source distribution
of Mercury on Windows using Cygwin.  This installation will use the GNU
C compiler by default.  If you want to use the Microsoft Visual C
compiler, please see the file README.MS-VisualC.

-----------------------------------------------------------------------------

PREPARATION

To use or build Mercury on Windows, you need to first get Cygwin and
install it.  Cygwin version 1.3.1 is buggy and should not be used, but
Cygwin 1.1.* or Cygwin 1.3.2 or later should be OK.  Recent versions of
Cygwin can be installed directly from:

	<http://cygwin.com/setup-x86.exe>

This program will download and install the required components.

If you want more information on Cygwin, see the site:

	<https://cygwin.com>

If you're going to use a binary distribution of Mercury for Windows,
you need to make sure that you get a version of Cygwin that is
compatible with the one that the binary distribution was compiled
with.  This will normally be specified in the filename of the
Mercury binary distribution.  For example, if the file name is
mercury-0.9.1.pc-windows-cygwin-1.1.4.tar.gz then you need version
1.1.4 of Cygwin.  Later versions may work also, however it is always
possible that compatibility might break at some point.  Cygwin will
create a file C:\cygwin\setup.txt that lists the versions of every
package installed.

Before continuing, check that you can run Cygwin and get a command line
shell, and that `gcc' (the GNU C compiler) works.

For more information on Cygwin, see the Cygwin web site mentioned above.

-----------------------------------------------------------------------------

UNPACKING THE SOURCES

After installing Cygwin, you should download the Mercury source or
binary distribution, and unpack it.

You should use Cygwin's tar program to unpack the Mercury distribution.
From a cygwin command shell, use the `cd' command to change directory
to the directory where you saved the source or binary distribution that
you downloaded, and then use `tar zxf <filename>' to unpack it,
where <filename> is the filename that you downloaded, e.g.
mercury-compiler-<VERSION>.tar.gz (for the source distribution), or
mercury-<VERSION>.i686-pc-cygwin-windows.tar.gz (for the binary distribution).

Note that other programs which understand tar.gz files (e.g. WinZip)
may not be able to unpack them in the correct manner for use with Cygwin.

-----------------------------------------------------------------------------

RUNNING CONFIGURE

Use the `cd' command to change directory to the directory that you just
unpacked, and then configure with

	sh configure

as described in the INSTALL file.
On Windows 2000 or XP, it may start up the "Microsoft Management Console"
program (the autoconfiguration process looks for a program named "mmc").
If so, just close that application, e.g. by selecting "Exit" from
the "Console" menu.

-----------------------------------------------------------------------------

RUNNING MAKE INSTALL

Just type

	make install

-----------------------------------------------------------------------------

USING MERCURY

Once you've finished installing, you need to add the appropriate
directory, normally /usr/local/mercury-<VERSION>/bin, to your PATH. 
If you are familiar with how to set the PATH for command-line programs
in Windows you can add 

	C:\cygwin\usr\local\mercury-<VERSION>\bin

to that path.

Otherwise you can just set the path in Cygwin by creating a file called
`.bashrc' in your Cygwin home directory that contains the line: 

	PATH=/usr/local/mercury-<VERSION>/bin:$PATH

You Cygwin home directory can be found in C:\cygwin\home\username\ 
if using Windows Explorer (Cygwin will call your home directory
`/home/username' or simply `~').

On Windows 2000, you need to make sure that this directory precedes
the Windows system directory in the PATH, otherwise `mmc' will invoke the
Microsoft Management Console rather than the Melbourne Mercury Compiler.
In this case it might be a good idea to modify your path in your
.bashrc rather than in the Windows PATH environment variable, so as to
not confuse any other programs that might be looking for the Microsoft
Management Console.

You should be able to read the HTML version of the Mercury
documentation, which by default gets installed in
C:\cygwin\usr\local\mercury-<VERSION>\lib\mercury\html, using Netscape
or MS Internet Explorer.  Or you can get a copy of GNU Emacs
for NT and use it to browse the INFO version.

If you use mmake files named `Mmake' rather than `Mmakefile',
there can be some problems with case-insensitive filenames
and the name clash between `mmake' and `Mmake'.  If you run into any
such problems, rename your `Mmake' file to `Mmakefile'.

To write Mercury programs, simply create a new .m file in your favourite
editor.  Run `mmc <filename>.m' on the Cygwin command line to compile
small programs, or use `mmake' to handle larger systems.  See the
Mercury Users Guide for more information about the command line tools.
There is currently no GUI for editing and compiling Mercury programs,
although it is quite likely you can hook up a sophisticated editor to
run `mmc' and/or `mmake' for you.

-----------------------------------------------------------------------------

MEMORY ALLOCATION

By default no Cygwin program can allocate more than 384 MB of memory
(program+data).  It is possible to exceed this limit, especially if one
is using a debugging grade.  In which case the runtime will report the
following error

	"GC Warning: Out of Memory!  Returning NIL!"

To increase the maximum amount of memory a cygwin program can consume
execute the following command, replacing 1024 with a value that makes
sense for your system.

regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024

See <http://cygwin.com/cygwin-ug-net/setup-maxmem.html> for more
details.

-----------------------------------------------------------------------------