         Copyright (c) NetHack Development Team 1990-2002
         NetHack may be freely redistributed.  See license for details.
         ==============================================================
                    Instructions for compiling and installing
                 NetHack 3.4 on a Windows NT, 2000, or XP system
         ==============================================================
		      Last revision: March 2, 2002

{TODO: there are some TODO's in the text below to be resolved before release}

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.

The PC Windows porting team consisting of Michael Allison, Dave Cohrs, 
Alex Kompel, Yitzhak Sapir, and Janet Walz integrated the tty version 
and the graphical version into the NetHack 3.4.0 sources.  Just as
the release of NetHack 3.4.0 was being prepared, Dion Nicolaas submitted 
an entire win32 port of his own to the NetHack Development Team. Dion was
subsequently invited to join the PC Windows porting team where he could 
continue to contribute to the win32 port, and that invitation was accepted.


You can build either the TTY version of NetHack or the Windows Graphical 
version.  In either case you can use one of the following build
environments:

  o A copy of Microsoft Visual C V6.0 SP3 or later.  Things may work with 
    an earlier version of the compiler, but the current code has not been
    tested with an earlier version.
		
	OR

  o A copy of Borland C 5.5.1 command line tools.  Borland has made a
    version of its command line tools available for download after
    registration at:
    http://www.borland.com/bcppbuilder/freecompiler/.

Additionally, you can build a TTY version of NetHack with the following
build environment:

  o A copy of MinGW 1.0. MinGW is a collection of header files and import
    libraries with which native Windows32 programs can be made; MinGW 1.0
    ships with the GNU Compiler Collection.
    You can download MinGW at
    http://www.mingw.org/


FIRST STEP:

The first step in building either version of NetHack is to execute
sys/winnt/nhsetup.bat.  

From the command prompt:
	cd sys\winnt
	nhsetup

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

A "binary" directory will be created off the top of the NetHack source
tree to house the completed build.

A build subdirectory will also be created off the top of the NetHack 
source tree, and many files appropriate for a graphical build will be 
moved there.

If you wish to build the TTY version, proceed now to "BUILDING TTY VERSION."
If you wish to build the graphical version, proceed now to "BUILDING GRAPHICAL VERSION."


------------------------
| BUILDING TTY VERSION |
------------------------

This version of NetHack for Win32 is a tty port utilizing the WIN32 
Console I/O subsystem.

I.  Dispelling the Myths:

    Compiling NetHack for WIN32 TTY 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 C++ V6.0 SP3 or greater
        o Borland C 5.5.1
        o MinGW 1.0 with GCC 2.95.3-6

    The Microsoft Visual C 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 32-bit compiler, but 
    that has not been tested. 

    The Borland C Makefile was created for use with Borland MAKE 
    which is provided with the Borland compiler.

    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 32 bit Windows machine (NT or 2000):
    (Note: build has not been tested on Windows XP.  That isn't to say that
           it doesn't work, it just hasn't been tried by us.)

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.  (Examples: For the Microsoft compiler by
    executing vcvars32.bat, which is probably in the bin directory of 
    your compilers directory tree. For the Borland Makefile, you can 
    simply invoke the Make utility from the Makefile's directory (For 
    the standard Borland compiler installation you can just 
    use the explicit path "c:\borland\bcc55\bin\make /f Makefile.bcc".
    For the GCC Makefile, add <mingw>\bin to your path, where <mingw> is
    your MinGW root directory.)

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, win\tty, and
    binary (The "binary" directory was created by nhsetup.bat earlier 
    if you followed the steps appropriately).

    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  
 

    Check the file "Files" in your top level directory for an exact
    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 the WIZARD option.

    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. 

    For building the TTY version, ensure that GRAPHICAL is set to "N",
    or commented out.  (If you aren't building the TTY version, you are
    currently reading the wrong section, and following the wrong set of
    steps.  In that case, you may wish to start reading from the top
    again.)

    Optional step:
      If you elected not to use the high-quality BSD random number routines by
      commenting out RANDOM in ntconf.h, comment out (or set equal to nothing) 
      the RANDOM macro in your Makefile.

    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, change your current directory to src.

    For Microsoft compiler: 
        nmake install

    For Borland compiler:
        make /f Makefile.bcc install

    For GCC:
        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.

Running NetHack

6.  Make sure all of the support files -- Guidebook.txt, license,
    Defaults.nh, NetHack.exe, nhdat, and recover.exe -- were copied to the 
    game directory.  If not, move them there yourself.

    Edit Defaults.nh to reflect your particular setup and personal 
    preferences, by following the comments.  As with all releases since
    3.2.1, HACKDIR defaults to the same directory as that where the NetHack.exe
    executable resides.  You only need to set HACKDIR in defaults.nh if,
    for some reason, you wish to override that (be careful).
  
7. Executing the game

    a) Running from the command prompt:

    If you add the directory containing the NetHack executable
    to your PATH, you can just type "nethack" or "nethack -umike"
    to start it up.  Alternatively, you can explicitly invoke it with 
    a command such as "c:\nethack\binary\nethack.exe" (specifying whatever 
    drive and directory your NetHack executable resides in) each time.

    b) Running from a Windows shortcut.

    If you will be running it by launching it from a shortcut, just 
    use the following information when setting up the shortcut.

         Description      :  NetHack 3.4.0 
         Command Line     :  C:\NETHACK\BINARY\NETHACK.EXE

   (changing the directory to the appropriate one of course)

8. Play NetHack.  If it works, you're done!

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 Borland compiler:
        make /f Makefile.bcc

    For GCC:
        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)  The executable produced by the TTY build is a 32-bit, flat-address space, 
    non-overlayed .exe file, which should run on any true Win32 environment
    with console I/O support. 


------------------------------
| BUILDING GRAPHICAL VERSION |
------------------------------


This version of NetHack is a Win32 native port built on the Windows API.

I.  Dispelling the Myths:

    Compiling NetHack for Windows is straightforward, as long as you have 
    your compiler and tools correctly installed.  

    It is also assumed that you already changed your directory to 
    sys\winnt and executed:
	nhsetup
    as described at the top of this document. If you didn't, you must
    go back and do so before proceeding.

II. To compile your copy of NetHack for Windows on a 
    Windows NT/2000/XP machine:

Setting Up

1.  It almost goes without saying that you should make sure that your tools
    are set up and running correctly. (Examples: For the Microsoft Visual
    Studio C compiler it should correctly fire up when you choose it in
    your Start | Programs menus, and for Borland make sure that the compiler
    is in your PATH, or that you know where the make.exe executable resides.)

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, win\win32, 
    and at this point you should also have a build directory and a
    binary directory (both created by nhsetup.bat executed from 
    sys\winnt earlier.)

    Other subdirectories may also be included in your distribution, but
    they are not necessary for building the graphical version of NetHack
    (you can delete them to save space if you wish.)

    Required Directories for a Win32 Graphical NetHack:

                            top
                             |
        -----------------------------------------/ /--------------- 
        |     |    |      |     |   |      |           |       |
       util  dat  doc  include src sys    win        build    binary
                                    |      |
                                  ------   -----
                                  |    |       |    
                               share  winnt  win32
 
    Those last two (build and binary) are created during the building
    process.  They are not disributed as part of the NetHack source 
    distribution.  nhsetup.bat creates the build directory and moves 
    a few files into it, including the Visual C project files.
    The "binary" directory will house everything you need to play the 
    game after building is complete.

    Check the file "Files" in your top level directory for an exact
    listing of what file is in which directory.  In order for the
    build process to work, all the source files must be in the proper
    locations.  Remember that nhsetup.bat moves/copies many files around
    to their intended locations for building NetHack.

    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.  Visual Studio project
    files and workspace files (dsp and dsw files) in particular need to 
    have their lines end in carriage-return-line-feed or they won't work
    properly.

3.  Ready your tool.
    Microsoft compiler users, perform step 3a.
    Borland compiler users, perform step 3b.

    Note for Microsoft users: It's possible to build a graphical version
    using the Makefile.  For simplicity's sake, however, only the Visual
    C IDE build will be explained.  The IDE build has full game
    functionality and is the officially released build.s

    a) Microsoft compiler:
       Start the Visual C IDE. In the Visual C IDE Menus, choose:
           File | Open Workspace

    b) Borland compiler:
       Chdir to the NetHack src directory:
           chdir ../../src
       if your current directory was still sys/winnt, 
       or:
           chdir src
       if your current directory was the top of the NetHack tree.

4.  Set up for the build.
    Microsoft compiler users, perform step 4a.
    Borland compiler users, perform step 4b.

    a) Microsoft compiler only:
        o In the Visual C "Open Workspace" dialog box, navigate to the top
            of  your NetHack source directory.
 
            In there, highlight "nethack.dsw" and click on Open.
            Once the workspace has been opened, you should see the following
            list in the Visual C selection window:
              + dgncomp files
              + dgnstuff files
              + dlb_main files
              + levcomp files
              + levstuff files
              + makedefs files
              + nethackw files
              + recover files
              + tile2bmp files
              + tilemap files
              + uudecode files

        o On the Visual C menus, choose:
              Project | Set Active Project | nethackw

        o On the Visual C menus again, choose either:
              Build | Set Active Configuration | nethackw - Win32 Release
            or
              Build | Set Active Configuration | nethackw - Win32 Debug

            The first will create the Release build of NetHackW which does
            not contain all the debugging information and is smaller, and
            runs quicker.  The second will create the Debug build of NetHackW
            and will spend a lot of time writing debug information to the disk
            as the game is played. Unless you are debugging or enhancing NetHack 
            for Windows, choose the Release build.

        o For Microsoft compiler build, you may now proceed to step 5.

    b) Borland Compiler only:

        o Edit the Makefile. Ensure the following are set correctly.
          GRAPHICAL should be set to "Y"

        o Ensure that all your tools directories are set up properly.
          By default, your tools are assumed to be in the same
          directory as the MAKE program.


Building
    
5.  Start your build.
    Microsoft compiler users, perform step 5a.
    Borland compiler users, perform step 5b.

    a) Microsoft Compiler only:
        o On the Visual C menus once again, choose:
              Build | Build nethackw.exe
          This starts the build.  It is likely that the IDE message window 
          where you are doing the compiling will be occupied for a while.
          If all goes well, you will get an NetHack executable called 
          nethackw.exe in the "binary" directory, along with all the support
          files that it needs.

        o For Microsoft compiler build, you may now proceed to step 6.

    b) Borland Compiler only:
        o With your current directory the NetHack src directory,
          issue the following command:
              make /f Makefile.bcc install

6.  If all has gone well to this point, you should now have a playable 
    game of "NetHack for Windows" in the "binary" directory.
 

Running NetHack

7.  Make sure all of the support files -- Guidebook.txt, license,
    Defaults.nh, nethackw.exe, nhdat, and recover.exe 
    -- were copied to the binary directory.  
    (If not, find them in the tree and move them there yourself if they
     exist.  If they don't exist, something has gone wrong)

    Edit Defaults.nh to reflect your particular setup and personal 
    preferences, by following the comments.  As with all releases since
    3.2.1, HACKDIR defaults to the same directory as that where the nethackw.exe 
    executable resides.  You only need to set HACKDIR in Defaults.nh if, 
    for some reason, you wish to override that (be careful).
  
8.  Executing the game
    a) Running from the command prompt:

    If you add the directory containing the NetHack executable
    to your PATH, 
    You can just type "nethackw" to start it up.  Alternatively, you 
    can explicitly invoke it with a command such as 
    "c:\nethack\binary\nethackw.exe" (specifying whatever drive 
    and directory your NetHack executable resides in) each time.

    b) Running from a Windows shortcut (win95 or NT4.x)

    If you will be running it by launching it from program manager
    or from a shortcut, just use the following information when 
    setting up the icon or shortcut.

         Description      :  NetHack 3.4.0 
         Command Line     :  C:\NETHACK\BINARY\NETHACKW.EXE

   (changing the directory in the Command Line to the appropriate one of course)

9. Play NetHack for Windows.  If it works, you're done!


PROBLEMS

    If you encounter a bug and wish to report it, please send e-mail to:
        nethack-bugs@nethack.org

    If you have any comments or suggestions, feel free to drop us a line c/o:
        DevTeam@nethack.org

    You may wish to vist the NetHack Development Team's website occasionally
    to check for updates or known bugs.  The website can be found at:
             http://www.nethack.org/

    Happy NetHacking!
