         Copyright (c) NetHack Development Team 1990-2023
         NetHack may be freely redistributed.  See license for details.
         ==============================================================
                  Instructions for compiling and installing
                       NetHack 3.7 on a Windows system
                     (Windows 7/8.x/10/11 or later only)
         ==============================================================
          Last revision: $NHDT-Date: 1594155895 2020/07/07 21:04:55 $

Credit for the porting of NetHack to the Win32 Console Subsystem goes to
the NT Porting Team started by Michael Allison.

Credit for the Win32 Graphical version of NetHack (aka "NetHack for
Windows" or NetHackW) goes to Alex Kompel who initially developed and
contributed the port.

Alex Kompel, Dion Nicolaas, Yitzhak Sapir, Derek S. Ray, Michael Allison,
Pasi Kallinen, Bart House, and Janet Walz contributed to the maintainance
of the tty and graphical windows versions of NetHack 3.7.0.

The build Makefiles and procedures produce two executables:
    a. A TTY and curses version of NetHack in nethack.exe
    b. A Windows Graphical version in nethackw.exe.

You can use one of the following build environments:
  o A copy of Microsoft Visual Studio 2017 Community Edition or
    a copy of Microsoft Visual Studio 2019 Community Edition or
    a copy of Microsoft Visual Studio 2022 Community Edition

    OR

  o An up-to-date copy of MinGW-w64. MinGW-w64 is a collection of
    GNU C Compiler (GCC) executables, headers, files and import
    libraries. The official site for MinGW-w64 is
        https://www.mingw-w64.org/
    There are a few packaged distributions of MinGW-w64. We've tried
    out these ones, but there are likely others that will work:

        MSYS2 
        - https://www.msys2.org/
        - Download the installer, and start the appropriate bash shell.

        MinGW-w64 - winlibs standalone build
        - https://github.com/brechtsanders/winlibs_mingw
        - Download one of the releases from
          https://github.com/brechtsanders/winlibs_mingw/releases
          and extract the contents into a folder (ideally in a folder
          without spaces in the path), and add the location of the
          subfolder containing gcc.exe to your PATH.

/---------------------------------------------\
|    Directories for a Win32 NetHack build    |
\---------------------------------------------/


               (NetHack-top)
                     |
  +-----+-----+------+------+-----+-------------+------~------+
  |     |     |      |      |     |             |             |
 util  dat   doc  include  src   sys           win        submodules
                                  |           |               |
                              +------+      +------+    +-----------+
                              |      |      |      |    |           |
                            share windows tty   win32  lua       pdcurses
                                     |
                                    vs

/-----------------------------------------------------------------------\
| Required components that are not bundled in the NetHack repository     |
\-----------------------------------------------------------------------/

NetHack 3.7 for Windows requires some 3rd party sources that are not
directly distributed within the NetHack repository, but they are configured
as submodules if you are online and have git, or you can obtain them
yourself.

Via git (recommended)

    If you obtained your NetHack sources by cloning from a git repository such
    as https://github.com/NetHack/NetHack and you have git installed and
    available and you are online, you simply need to execute the following
    command from the top level NetHack folder to populate source code into the
    submodules/lua and submodules/pdcurses folders:

    git submodule init
    git submodule update


Via zip download

    If you obtained your NetHack sources from a zip file or source other than
    via git, you'll have to obtain Lua and pdcurses from their respective
    locations (at the time of this writing).
    Windows 10 or newer is assumed below, because wget and tar started to be
    included in that version.

    o obtain Lua
        cd lib
        wget http://www.lua.org/ftp/lua-5.4.6.tar.gz
        tar -xvf lua-5.4.6.tar.gz
        cd ..

    o obtain pdcursesmod
        cd lib
        wget --no-check-certificate ^
             https://github.com/Bill-Gray/PDCursesMod/archive/refs/tags/v4.3.7.tar.gz ^
             --output-document=pdcursesmod.tar.gz
        tar -xvf pdcursesmod.tar.gz
        ren PDCursesMod-4.3.7 pdcursesmod
        cd ..

    o update your Makefiles to reflect:

      In sys/windows/Makefile.mingw32
        change from
            PDCURSES_TOP = ../submodules/pdcurses
        to
            PDCURSES_TOP = ../lib/pdcurses

        change from
            LUATOP = ../submodules/lua
        to
            LUATOP = ../lib/lua-5.4.6

      In sys/windows/Makefile.nmake
        change from
            PDCURSES_TOP = ..\submodules\pdcursesmod
        to
            PDCURSES_TOP = ..\lib\pdcursesmod

        change from
            LUATOP = ..\submodules\lua
        to
            LUATOP = ..\lib\lua-5.4.6

/-----------------------------------------------------------\
| Building And Running Using Visual Studio 2017, 2019, 2022  |
\-----------------------------------------------------------/

If you are NOT using Visual Studio IDE, or you prefer to build
using a Make utility and a Makefile proceed to "Building Using Make".

When using either Visual Studio 2017, 2019, or 2022, you simply need to
load the solution file within the IDE, build the solution and  run the version
of NetHack you wish to run.

The Visual Studio NetHack solution file can be found here:
    sys\windows\vs\NetHack.sln

Before executing the steps to build listed in the next paragraph,
decide if you want to include optional curses window-port. See
the note just below entitled "Optional curses window-port support."

So the steps are:
    1. Launch the IDE.
    2. Open the appropriate solution file.
    3. Select the build configuration you wish to use (Release, Debug, etc.).
    4. From the build menu, select build solution.
    5. Type F5 to start debugging.

 * Optional curses window-port support *

Since 3.6.2, the community patch for a window-port that uses curses has been
incorporated into the NetHack source code tree. That window-port, which
evolved from work originally done by Karl Garrison, has been used in several
NetHack variants and on nethack.alt.org and on www.hardfought.org/nethack/.

If you want to include the curses window-port support in your Visual Studio
build, you will have to first obtain the PDCurses sources from
https://github.com/wmcbrine/PDCurses
and have them available prior to building NetHack. There are two ways to
enable curses window-port support during the VS build: Either set the
environment variable PDCURSES to a folder containing a PDCurses
repository/source-tree
    OR
Place the PDCurses folder alongside the NetHack source repository prior
to proceeding with steps 1 through 5 above.


/-------------------------------------------\
| Building From the Command Line Using Make |
\-------------------------------------------/

--------------------------------------------------------------------------
-- Beginning of prerequisite step --

The first step in building either version of NetHack via Makefile is to
execute sys\windows\nhsetup.bat to move some files to their required locations.

From the command prompt:
        cd sys\windows
        nhsetup

From a Windows explorer window:
        double-click on nhsetup.bat

If you wish to build from the command line, proceed to "BUILDING FROM
THE COMMAND LINE."

-- end of prerequisite step --
--------------------------------------------------------------------------

Two different versions of NetHack will be built for Windows from the
command line using the Makefile approach:
    A tty port utilizing the Win32 Console I/O subsystem, Console
        NetHack;
    A Win32 native port built on the Windows API, Graphical NetHack or
        NetHackW.

The executable for Console NetHack will be named NetHack.exe. The
executable for Graphical NetHack will be named NetHackW.exe. The
Makefile configuration will build both; NetHackW.exe and NetHack.exe
will be able to use the same datafiles, save files and bones files.

Since the last official release of NetHack, compilers and computer
architectures have evolved and you can now choose whether to build
a 32-bit x86 version, or a 64-bit x64 version.  The default Makefile
is set up for a 32-bit x86 version, but that's only because it will
run on the most number of existing Windows environments.

NetHack's save files and bones files in the 3.7.0 release have not yet
evolved enough to allow them to interchange between the 32-bit version
and the 64-bit version (or between different platforms). Hopefully
that will change in an upcoming release.

I. Dispelling the Myths:

    Compiling NetHack for Windows is not as easy as it sounds, nor as hard
    as it looks, however it will behoove you to read this entire section
    through before beginning the task.

    We have provided a Makefile for each of the following compilers:

        o Microsoft Visual Studio 2017 or 2019 or 2022 C++ Compiler
          The Community Editions are fine and available at no cost
        o MinGW-w64

    The Microsoft Visual Studio makefile was created for use
    with MS NMAKE which is provided with the Microsoft compiler.
    The supplied Makefile may work with earlier versions of the Microsoft
    compiler, but that has not been tested.

    The GCC Makefile was created for use with GNU Make.

II. To compile your copy of NetHack on a Windows machine:

Setting Up

1.  It almost goes without saying that you should make sure that your
    tools are set up and running correctly.  That includes ensuring that
    all the necessary environment variables for the compiler environment
    are set correctly.

    Change your current directory to the src subfolder of the nethack
    source tree.
        cd src

2.  Since 3.6.2, the community patch for an optional curses window-port
    has been incorporated into the NetHack source code tree. That
    window-port, which evolved from work originally done by Karl Garrison,
    has been used in several NetHack variants and on nethack.alt.org and
    on www.hardfought.org/nethack/. The optional curses window-port is
    available for Windows, macOS, and Unix (and also DOS).

    The Makefiles are configured by default to include the curses
    window-port support in your command line Makefile build.

3.  Make sure all the necessary files are in the appropriate directory
    structure.  You should have a main NetHack top directory with
    subdirectories dat, doc, include, src, sys\share, sys\windows,
    win\tty, util.

    (You can check the file "Files" in your top level directory for a
     more complete listing of what file is in which directory.)

    If you downloaded or ftp'd the sources from a UNIX system, the lines
    will probably end in UNIX-style newlines, instead of the carriage
    return and line feed pairs used by Windows.  Some programs have
    trouble with them, so you may need to convert them. The compiler
    should not have any problems with them however.

4.  Edit your Makefile if you wish, but it is not required unless
    you are altering the build options.

Compiling

5.  Now that everything is set up...

    Change your current directory to the NetHack src directory.

    For the Visual Studio compiler:
	Issue these commands:
            copy ..\sys\windows\Makefile.nmake Makefile
	    nmake install

    For GCC:
	Issue these commands:
            cp ../sys/windows/Makefile.mingw32* .
            mingw32-make -f Makefile.mingw32 clean
            mingw32-make -f Makefile.mingw32 depend
            mingw32-make -f Makefile.mingw32

    If you get any errors along the way then something has not been set
    up correctly. The time it takes to compile depends on your
    particular machine of course, but you should be able to go for lunch
    and return to find everything finished.  The less memory, and slower
    your machine, the longer the lunch you may take. :-)

    In any case, it is likely that the command prompt window where you
    are doing the compiling will be occupied for a while.  If all goes
    well, you will get an NetHack executable.

Notes:

1.  To install an update of NetHack after changing something, change
    your current directory to src and issue the appropriate command for
    your compiler:

    For Microsoft compiler:
        nmake

    For GCC:
        mingw32-make -f Makefile.mingw32

    If you add, delete, or reorder monsters or objects, or you change
    the format of saved level files, delete any save and bones files.
    (Trying to use such files sometimes produces amusing confusions on
    the game's part, but usually crashes.)

2.  Depending on the build and compiler and tools used above, the
    executable produced by the TTY build is either:
      - a 32-bit (x86) .exe file,
        which should run on any recent Win32 environment.
    or
      - a 64-bit (x64) .exe file,
        which should run on any 64-bit Windows O/S.

    **Note**: saved games are NOT compatible between the 32-bit and the
    64-bit versions at this time. 

NetHack.exe is the tty plus curses version. NetHackW.exe is the windows
graphical version.

Play NetHack.

PROBLEMS

    If you discover a bug and wish to report it, or if you have comments
    or suggestions we recommend using our "Contact Us" web page at:
        http://www.nethack.org/common/contact.html

    If you don't have access to the web, or you want to send us a patch
    to the NetHack source code feel free to drop us a line c/o:
        DevTeam (at) nethack.org

    Happy NetHacking!
