= A note on Windows/MinGW support

Now you can compile Gauche to use MinGW runtime library.  It is
the recommended way to build Gauche on Windows.  (You may still be
able to build with Cygwin but it has a few quirks that interfere
with Gauche that may surprise you.)

Because of the difference of the underlying system, not all
system-related procedures are available on MinGW port.
The reference manual tells whether a particular procedure
is supported on "`Windows native`".

As of 0.9.5, the official Windows binaries are built with
mingw-w64 (see link:https://www.mingw-w64.org/[]).  It may still be
built with the original MinGW, but our support efforts are
prioritized in favor of mingw-w64.  By '`MinGW version`' in
the following sections, we mean Gauche built with mingw-w64.

If you just want to use Gauche on Windows, you can use the binary
installer.  Below, we describe what you need to build Gauche
from the source.


== Prerequisites

You need the following software:

=== link:https://www.msys2.org/[MSYS2]

Download the installer and follow the instruction.  I recommend
to leave the installation folder default (`C:\msys64`, for x86_64).
After setup wizard finished, do not forget to follow the instruction
in the above site to update packages.

Once MSYS2 is in place, you can get mingw-w64 toolchain using
`pacman`.  Fire MSYS2 shell and type `+pacman -S <package> ...+`.
For +mingw-w64-***+ packages, choose suitable architecture.

The following packages are needed:

- base-devel
- mingw-w64-ucrt-x86_64-toolchain
- mingw-w64-ucrt-x86_64-autotools

The following packages are strongly recommended.  Gauche can be built
without them, but some features will not be available.

- mingw-w64-ucrt-x86_64-zlib (included in toolchain)
- mingw-w64-ucrt-x86_64-libiconv (included in toolchain)
- texinfo (included in base-devel)

The following packages are used if you wand to compile MbedTLS within
Gauche.  See "Build with MbedTLS" below for the details.

- cmake
- python3


[NOTE]
====
`pacman` tries to install packages under `C:/msys64/mingw64` etc,
but sometimes the first attempt fails saying:

----
error: failed to commit transaction (conflicting files)
....  /mingw64 exists in file system
----

There is `/mingw64.exe` and `/mingw64.bat` (in msys2 file system) and
the installer gets confused.  Manually creating directory `/mingw64`
will solve the problem.
====

=== Gauche

You need the latest release version of Gauche in order to build
Gauche from git source.  Install it using binary installer, or,
get a tarball and build it with MSYS2.

Make sure that `gosh` is visible from the `PATH` of your MSYS shell.


=== link:http://wixtoolset.org[Wix toolset]

(Optional) This is used to create installer.   If you just want
to build just for your machine, you don't need this.


== Build

You can build it just like on any other Unix systems; but for your
convenience, there's a script `src/mingw-dist.sh` which builds Gauche
in a way that you can zip and copy the resulting binary elsewhere,
or build a binary installer.

If you start from git repo clone (instead of source tarball), you
have to run `./DIST gen` first to generate configure scripts.

Once configure scripts are in place, run the `mingw-dist.sh` on the
*MSYS2 UCRT64 shell* (not MSYS2 MSYS shell) as follows:

[source,sh]
----
src/mingw-dist.sh
----

The compiled binaries are in `../Gauche-mingw-dist/Gauche-ucrt-x86_64`.
It includes DLLs needed to run `gosh`, so you can just zip
the directory and copy to whatever machine you like.


== Build with Gauche-gl

If you have link:https://github.com/shirok/Gauche-gl[Gauche-gl] source
tree aside of Gauche source tree
(that is, from Gauche's `$top_srcdir`, you have `../Gauche-gl`),
you can build Gauche-gl as well.  Give `--with-gl` option:

[source,sh]
----
src/mingw-dist.sh --with-gl
----


== Build with MbedTLS

In order to create TLS connection, you need to include MbedTLS support.
You can choose either to embed MbedTLS in the binary, or to depend
on external MbedTLS DLL.

To embed MbedTLS support, give `--with-mbedtls` option to `mingw-dist.sh`.
The MbedTLS source is downloaded and compiled during build.

[source,sh]
----
src/mingw-dist.sh --with-mbedtls
----

If you choose this, you need CMake and Python3 installed on your system,
which is required to build MbedTLS.

Note: If you build a Gauche binary in this way, it includes MbedTLS library
which is covered by Apache License 2.0.  Distributing the binary will
be covered by that license, as well as BSDL.

To build Gauche to use extenral MbedTLS DLL, give `--with-mbedtls=dll` option
instead:

[source,sh]
----
src/mingw-dist.sh --with-mbedtls=dll
----

If you choose this, Gauche binary does not include MbedTLS and hence
not bound to its license.  However, you need MbedTLS DLL on the
target machine to use TLS features.


== Build installer

Make sure `candle.exe` and `light.exe` (WiX toolset) are in the `PATH`.

Run `src/mingw-dist.sh` with `--with-installer` option, for example:

[source,sh]
----
src/mingw-dist.sh --with-gl --with-installer
----

This creates installer file `../Gauche-mingw-X.X.X-{32|64}bit.msi`.
