         Copyright (c) NetHack Development Team 1990-2006
         NetHack may be freely redistributed.  See license for details.
         ==============================================================
                 Instructions for compiling and installing
             NetHack 3.5 on a Windows 9x, NT, 2000, or XP system
         ==============================================================
                 Last revision: $Date$

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, David Cohrs, 
Alex Kompel, Dion Nicolaas, Yitzhak Sapir, and Janet Walz maintained the 
tty and graphical win32 versions of NetHack 3.5.0.

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, SP4, SP5, or SP6). 
    The C compiler that can be downloaded as part of the 
    Visual Studio 2005 Express Edition also works, but you must 
    also download the MS Platform SDK in order to build native win32 
    applications such as NetHack. The current NetHack code has not 
    been tested with other versions of the Microsoft compiler.		
		
    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/

    OR

  o A copy of MinGW 2.0 or later. MinGW is a collection of header 
    files and import libraries with which native Windows32 programs 
    can be built; the MinGW 2.0 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.
    
In addition to the makefiles that allow you to build NetHack from the
command line, there is also a set of project files and a workspace file
that allow you to build the Windows Graphical version from Microsoft
Visual C's IDE (Integrated Development Environment.)


/-----------------------------------\
| FIRST STEP - MOVING THINGS AROUND |
\-----------------------------------/

The first step in building either version of NetHack 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

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 from the command line, proceed to "BUILDING FROM
THE COMMAND LINE."

If you wish to build using Visual C's IDE, proceed now to "BUILDING
USING VISUAL C'S IDE."

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

You can built two different versions of NetHack for Win32 from the
command line:
    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. You can opt
to build both; they will be able to use the same datafiles, save files
and bones files.

I. Dispelling the Myths:

    Compiling NetHack for Win32 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 - SP6) and 
          Microsoft Visual C++ 2005 Express Edition with the Platform SDK
        o Borland C 5.5.1
        o MinGW 2.0 (with GCC 3.2)

    The Microsoft Visual C Makefile was created for use with MS NMAKE 
    which is provided with the Microsoft compiler. The supplied Makefile
    has not been tested with any other versions of the Microsoft 32-bit
    compiler.

    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 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.  That includes ensuring that
    all the necessary environment variables for the compiler environment
    are set correctly. 

    For Visual C++ 6.x, you need to execute 
	vcvars32.bat 
    which is probably in the bin directory of your compilers directory tree.
  
    For Visual Studio 2005 Express Edition, you will need to download 
    and install the MS Platform SDK as well.  The Platform SDK is 
    required for building native WIN32 applications, such as NetHack. 
    The two must be integrated to work together once. 
    At the time of this writing, there were instructions available from 
    the manufacturer at the following URL:
      http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/

    Once you have Visual Studio 2005 Express and the Platform SDK 
    properly integrated with each other, you need to execute
        vcvarsall.bat
    which is probably in the bin directory of your VSINSTALLDIR.
    Then for the Platform SDK, you may also need to execute
        SetEnv.cmd
    from the Platform SDK install directory, especially if you installed
    Visual Studio 2005 Express Edition to a non-default location. You can 
    put the execution of those into a single .CMD file to make it easier 
    if you like.

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

    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". NetHack 3.5.0 has not
    yet been tested with the Borland compiler.


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

    For building Console NetHack, ensure that GRAPHICAL is set to "N",
    or commented out. For building Graphical NetHack, set GRAPHICAL to
    "Y".

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

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

    The executable built by the graphical built is a 32-bit,
    flat-address space, non-overlayed .exe file, which should run on any
    true Win32 graphical environment.

    To run NetHack, proceed to RUNNING NETHACK.

/--------------------------------\
| BUILDING USING VISUAL C's IDE  |
\--------------------------------/

Only the Win32 native port built on the Windows API, or Graphical
NetHack, can be built using the Visual C IDE.

I. Dispelling the Myths:

    Compiling NetHack using the Visual C IDE is straightforward, as long
    as you have your compiler and tools correctly installed.

    It is again 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 using the Visual C IDE:

Setting Up

1.  It almost goes without saying that you should make sure that your
    tools are set up and running correctly. (For the Microsoft Visual C
    IDE it should correctly fire up when you choose it in your Start |
    Programs menus.) 

    If you are using Visual C++ 2005 Express Edition, you must install
    both the Visual C++ 2005 Express Edition, and the Platform SDK.
    They are both freely downloadable at the time of this writing, but
    be warned that they are very large downloads. After installing the
    Visual C++ 2005 Express Edition, you will then need to install the 
    Platform SDK and integrate it with Visual C++ 2005 Express Edition
    in order to be able to build native WIN32 applications. At the time 
    of this writing, there was some assistance on how to integrate the 
    two products at the following URL:
    http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ 

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 building Graphical NetHack with the Visual
    C IDE:

                            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 C 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.
    Note: It's possible to build a graphical version using the Makefile,
    as explained above. However, the IDE build has full game
    functionality and is the officially released build.

    Start the Visual C IDE. 
    In the Visual C++ V6.0 IDE menus, choose:
        File | Open Workspace
    In the Visual C++ 2005 Express Edition IDE menus, choose:
        File | Open Project/Solution
     

4.  Set up for the build.

    In the Visual C dialog box, navigate to the top of
    your NetHack source directory.

    In there, highlight "nethack.dsw" for Visual C++ 6.0, or
    "nethack.sln" for Visual C++ Express Edition and click on Open.
    Once the workspace or solution has been opened, you should see 
    the following list in the Visual C selection left pane:
      + dgncomp
      + dgnstuff
      + dlb_main
      + levcomp
      + levstuff
      + makedefs
      + nethackw
      + recover
      + tile2bmp
      + tilemap
      + uudecode

    On the Visual C++ 6.0 menus, choose:
        Project | Set Active Project | NetHackW
    or for Visual C++ 2005 Express Edition, highlight 'nethackw' and
    select:
        Project | Set as Startup Project

    On the Visual C 6.0 menus again, choose either:
        Build | Set Active Configuration | NetHackW - Win32 Release
    or
        Build | Set Active Configuration | NetHackW - Win32 Debug
    In Visual C++ 2005 Express Edition, you can just choose "Debug" or
    "Release" right on the menu in the "solutions configuration" box.   

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

Building
    
5.  Start your build.

    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.

6.  If all has gone well to this point, you should now have a NetHack
    executable called NetHackW.exe in the "binary" directory, along with
    all the support files that it needs.
 

/-----------------\
| RUNNING NETHACK |
\-----------------/

I. Checking the installation:
    Make sure all of the support files -- Guidebook.txt, license,
    Defaults.nh, NetHack.exe or NetHackW.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 or NetHackW.exe executable resides.  You only need to
    set HACKDIR in defaults.nh if, for some reason, you wish to override
    that (be careful).
  
II. Executing the game

1.  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" or "nethackw"
    or "nethackw -umike" to start it up.  Alternatively, you can
    explicitly invoke it with a command such as
    "c:\nethack\binary\nethack.exe" or "c:\nethack\binary\nethackw.exe"
    (specifying whatever drive and directory your NetHack executable
    resides in) each time.

2.  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.5.0 Console version
        Command Line     :  C:\NETHACK\BINARY\NETHACK.EXE

        Description      :  NetHack 3.5.0 Graphical Interface
         Command Line     :  C:\NETHACK\BINARY\NETHACKW.EXE

   (changing the directory to the appropriate one of course)

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


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!
