This file documents the port of Mercury to Windows using either the MinGW
or MinGW-w64 ports of GCC, i.e. the i686-pc-mingw32, i686-w64-mingw32 or
x86_64-w64-mingw32, x86_64-pc-mingw32 and x86_64-pc-mingw64 configurations.

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

BUILDING WITH MINGW OR MINGW-W64

MinGW is a port of 32-bit GCC to Windows available from
<https://osdn.net/projects/mingw/>.

MinGW-w64 is a (different) port of both 64-bit and 32-bit GCC to Windows
available from <https://www.mingw-w64.org>.

MSYS is a POSIX-like environment available from <https://osdn.net/projects/mingw/>.

MSYS2 is a (different) POSIX-like environment.  It provides a package manager,
and among the packages it provides are the MinGW-w64 ports of GCC.
Note that MSYS2 is separate from the original MSYS.
It is available at <https://www.msys2.org>.

Using the MinGW or MinGW-w64 ports of GCC you can build a Mercury compiler that
can generate executables that will run natively on Windows without the need for
a support environment like Cygwin, MSYS or MSYS2.  Using the standard MinGW
version of GCC will result in a Mercury compiler that generates 32-bit
executables.  To build a Mercury compiler that generates 64-bit executables for
Windows you will need to use the MinGW-w64 port of GCC.

NOTE: a Unix-like environment is required to build and install the Mercury
compiler.  MSYS, MSYS2 or Cygwin can be used for this purpose.  A Unix-like
environment is only required for installing Mercury; you do *not* require one
to use Mercury once it is installed.

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

BUILDING A MINGW OR MINGW-W64 COMPILER UNDER MSYS

To build the source distribution under MSYS follow these steps:

1a. Download and install MinGW and MSYS from <https://osdn.net/projects/mingw/>

    In order to build and install Mercury you will require at least the
    following components:

    - MinGW Compiler Suite (C compiler)
    - MSYS Basic System
    - MinGW Developer Toolkit

    Details of alternative MinGW and MSYS installation methods may be found
    on the MinGW website.

    To build a version of the Mercury compiler that generates 64-bit
    executables using the MSYS shell, you will need to install the
    MinGW-w64 version of GCC (available from <https://mingw-w64.org>) and
    ensure that it occurs in your PATH before the MinGW GCC.

1b. Alternatively, download and install the MSYS2 environment from
    <https://www.msys2.org>

    You can use the MinGW-w64 version of GCC to build a copy of Mercury that
    generates 32-bit or 64-bit executables.  Start the "MinGW-w64 Win32 Shell"
    or "MinGW-w64 Win64 Shell".  First refresh the package database and install
    a few necessary tools:

	pacman -Sy tar make bison flex diffutils

    then install the desired version of gcc:

        pacman -S mingw-w64-i686-gcc
        pacman -S mingw-w64-x86_64-gcc

2.  Optional: To build the java grade with MinGW and MSYS / MSYS2 you will
    require the Windows version of the JDK to be installed on your system.
    The Java compiler (javac), Java archive tool (jar), and Java runtime (java)
    needs to be in the MSYS PATH, for example do the following in the shell:

        export PATH=/c/Program\ Files/Java/jdk1.6.0_23/bin/:$PATH 

    See README.Java.md for further details.

    Optional: To build the C# grade with MinGW, MSYS / MSYS2 and .NET, you will
    need Visual C# compiler installed on your system.
    The C# compiler (csc.exe) needs to be in your PATH, for example do the
    following in the shell:

        export PATH=/c/WINDOWS/Microsoft.NET/Framework/v4.0.30319/:$PATH
    
    See README.CSharp.md for further details.

3.  Unpack the source distribution with a command like:
    
        tar -xvzf mercury-compiler-<VERSION>.tar.gz

4.  cd into the new directory and run configure:

        ./configure --prefix=c:/mercury

    It is important to specify the installation prefix as a full windows
    path with a drive letter (except use `/' instead of `\').  
    Do not use a path like `/mercury', because that
    will be interpreted differently by the MSYS or MSYS2 shells than by the
    generated executables, resulting in a broken installation.

    If you are using the MSYS (not the MSYS2) shell with MinGW-w64 then you
    must also invoke configure with the following option:

       --host=x86_64-w64-mingw32

    This will cause mmake to use the MinGW-w64 tool chain.  Ensure that the
    MinGW-w64 tools are in your PATH before running configure.

    If you are using the MSYS2 shell then you need to launch it in either
    the "MSYS2 MinGW 32-bit" mode or the "MSYS2 MinGW 64-bit" mode to build
    a 32- or 64-bit Mercury system respectively.  You do not need to pass the
    --host option to configure script; it will detect the 32-bit or 64-bit
    MSYS2 environment you are running in.

5.  run: `make' and then `make install'.

Add /c/mercury/bin (or whatever path you installed Mercury to) to the MSYS or
MSYS2 PATH (you cannot add `c:/mercury/bin' to the PATH because `:' is used
to separate directories in the MSYS or MSYS2 PATH).

NOTE TO DEVELOPERS: the tools/bootcheck script does not work properly
on MSYS at the moment -- it will build stage 3, but will not run the tests
correctly.  To run the tests you should first install the compiler and add
it to the PATH.  Next set the DIFF_OPTS environment variable to "-c -b".  This
will cause the test scripts to ignore the extra carriage return character that
gets added to the end of each line under MinGW.  Then run mmake from the tests
directory.

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

BUILDING A CYGWIN COMPILER WHICH TARGETS MINGW

NOTE: recent versions of Cygwin no longer support the -mno-cygwin option.
Unfortunately the Cygwin documentation is silent on the matter of how
exactly you are now supposed to invoke the MinGW compiler from Cygwin;
until it is updated we recommend using MinGW/MSYS to build a MinGW
targeted compiler rather than Cygwin.

To build a compiler which targets MinGW from Cygwin do the following:

- First, install the Cygwin version of Mercury, and put it in your PATH.
- Second, configure the source distribution of Mercury using
  --with-cc="gcc -mno-cygwin".
- Third, run "make" and "make install".
- Fourth, replace the following files in the installed Mingw Mercury
  directories with copies of the corresponding file from the installed
  Cygwin Mercury directories:
        mercury_compile.exe (in <prefix>/lib/mercury/bin/<config>)
        mercury_profile.exe (in <prefix>/lib/mercury/bin/<config>)
        mdemangle.exe (in <prefix>/bin)
        mfiltercc.exe (in <prefix>/bin)
        mkinit.exe (in <prefix>/bin)

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