         Copyright (c) NetHack Development Team 1990-2018
         NetHack may be freely redistributed.  See license for details.
         ==============================================================
                  Instructions for compiling and installing
                       NetHack 3.6 on a Windows system
         (Windows 7/8.x/10 or later only. XP may work but is untested)
         ==============================================================
          Last revision: $NHDT-Date: 1524317622 2018/04/21 13:33:42 $

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.6.1.

You can build a TTY version of NetHack and a Windows Graphical 
version.  You can use one of the following build environments:

  o A copy of Microsoft Visual Studio 2017 Community Edition
    OR        Microsoft Visual Studio 2015 Express

    OR

  o (Untested for 3.6) A copy of MinGW. MinGW is a collection of header 
    files and import libraries with which native Windows32 programs 
    can be built; the MinGW distribution contains the GNU Compiler 
    Collection. You can download MinGW at
        http://www.mingw.org/
    Earlier versions of MinGW will not allow you to build the Windows
    Graphical version.

/--------------------------------------------------------\
| Building And Running Using Visual Studio 2015 or       |
|                            Visual Studio 2017          |
\--------------------------------------------------------/

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

When using either Visual Studio 2015 or Visual Studio 2017, 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 2015 NetHack solution file can be found here:
    win\win32\vs2015\NetHack.sln

The Visual Studio 2017 NetHack solution file can be found here:
    win\win32\vs2017\NetHack.sln

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.

You can also build all the projects for all platforms and configurations
using a "build.bat" batch file found in the same directory as the solution.

Open a developer command prompt for the version of Visual Studio you are
using.  Change to the appropriate directory (i.e. win\win32\vs2015 for
VS2015 builds, win\win32\vs2017 for VS2017 builds) and run "build.bat".

/-----------------------------------\
| Building Using Make               |
\-----------------------------------/

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

From the command prompt:
        cd sys\winnt
        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."

/--------------------------------\
| BUILDING FROM THE COMMAND LINE |
\--------------------------------/

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.6.1 release have not 
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 2015 or 2017 C++ Compiler
          The Community Editions are fine and available at no cost
        o MinGW 2.0 (with GCC 3.2)

    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 version 3.79.1,
    which comes with the MinGW package.

    You may find it useful to obtain copies of lex (flex) and yacc
    (bison, or byacc).  While not strictly necessary to compile nethack,
    they are required should you desire to make any changes to the level
    and dungeon compilers.

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

    GCC 

    For the GCC Makefile, add <mingw>\bin to your path, where <mingw> 
    is your MinGW root directory.).

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

2.  Make sure all the NetHack files are in the appropriate directory
    structure.  You should have a main directory with subdirectories
    dat, doc, include, src, sys\share, sys\winnt, util, and binary (The
    "binary" directory was created by nhsetup.bat earlier if you
    followed the steps appropriately).

    For Console NetHack you need win\tty in addition to these; for
    Graphical NetHack you need win\win32 in addition to these.

    Other subdirectories may also be included in your distribution, but
    they are not necessary for building the TTY version for the Win32 
    console subsystem.  You can delete them to save space.

    Required Directories for a Win32 Console NetHack:

                            top
                             |
        ----------------------------------------------------/ /----- 
        |       |     |        |       |     |          |        |
       util    dat   doc    include   src   sys        win     binary
                                             |          |
                                          ------      ----- 
                                          |    |      |    
                                       share  winnt  tty  
 

    Required Directories for a Win32 Graphical NetHack:

                            top
                             |
        ----------------------------------------------------/ /----- 
        |       |     |        |       |     |          |        |
       util    dat   doc    include   src   sys        win     binary
                                             |          |
                                          ------      ----- 
                                          |    |          |
                                       share  winnt      win32 
 
    Check the file "Files" in your top level directory for a more 
    complete listing of what file is in which directory.  In order for 
    the Makefiles to work, all the source files must be in the proper
    locations.

    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.

3.  Now go to the include subdirectory to check a couple of the header
    files there.  Things *should* work as they are, but since you have
    probably set up your system in some sort of custom configuration it
    doesn't hurt to check out the following:

    First check config.h according to the comments to match your system
    and desired set of features.  Mostly you need to check section 4 and
    5.

    You may include all or as few of the special game features as you
    wish (they are located last in the file).

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

    If you are recompiling after patching your sources, or if you got
    your files from somewhere other than the official distribution,
    "touch makedefs.c" to ensure that certain files (onames.h and pm.h)
    are remade, lest potentially troublesome timestamps fool your make
    (or nmake) utility.

Compiling

5.  Now that everything is set up...

    For the Visual Studio compiler, as mentioned above, you should now be
    at the command prompt to carry out the build and your current 
    directory should be the src subdirectory in the NetHack source tree.

    In the src subdirectory, issue this command:
	        nmake install

    For GCC:
	Change your current directory to the NetHack src directory.
	Issue this command:
        	mingw32-make -f Makefile.gcc install

    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.gcc

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

    If you made changes to any of the level compiler software, you may
    have to delete dgn_flex.c, dgn_yacc.c, lev_flex.c, and lev_yacc.c
    from the util directory to ensure that they are remade.

2.  Depending on the build and compiler and tools used above, the 
    executable produced by the TTY build is either:
      - a 32-bit (x86), flat-address space, non-overlayed .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.

NetHack.exe is the tty version. NetHackW.exe is the 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!
