	SCCS Id: @(#)Install.dos	 3.4		2000/08/02

	   Copyright (c) NetHack PC Development Team 1990-2000.
       NetHack may be freely redistributed.  See license for details.
       ==============================================================
              Instructions for compiling and installing
		     NetHack 3.4 on a DOS system
         ======================================================
                   (or, How to make PC NetHack 3.4)
                    Last revision: August 2, 2000

Credit for a runnable full PC NetHack 3.4 goes to the PC Development team
of Paul Winner, Kevin Smolkowski, Michael Allison, Yitzhak Sapir, Bill Dyer, 
Timo Hakulinen, Yamamoto Keizo, Mike Threepoint, Mike Stephenson, 
Stephen White, Ken Washikita and Janet Walz.  The present port is based
on the previous effort of Pierre Martineau, Stephen Spackman, Steve Creps, Mike
Threepoint, Mike Stephenson, Norm Meluch and Don Kneller.

CONTENTS:

        I.  Dispelling the Myths
        II. Compiling on a DOS machine
        Appendix A - Building the "official binaries"
        Appendix B - Building other binaries
        Appendix C - Microsoft C Compiler notes
        Appendix D - DJGPP Compiler (gcc ported to msdos) notes
        Appendix E - Borland C++ Compiler notes
        Appendix F - Microsoft C Compiler Warnings
        Appendix G - Additional Notes
        Appendix H - Contacting Us

I.  Dispelling the Myths:

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

    We have provided the proper makefiles for building NetHack using the
    following compilers:
	Microsoft C 7.0 and Microsoft Visual C++ Professional (MSVC) 1.52c
    	djgpp V2.0 or later
	Borland C V3.1

    For specific details concerning each compiler, please see the
    corresponding appendix.

    The makefile named Makefile.MSC is for use with Microsoft's NMAKE, 
    the make utility that ships with the Microsoft C Compiler version 7.0 
    and above, including the 16-bit Microsoft Visual C++ Professional.

    The makefile named Makefile.GCC is for use with GNU Make that
    accompanies djgpp.

    The makefile named Makefile.BC is for use with Borland's make that
    accompanies Borland C 3.1.  Other versions of Borland's make may or
    may not work, but version 3.7 (of MAKE) is known to not work.

    If you want to build a copy of NetHack that is identical to the
    "official binaries", please see appendix A.

    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.  Flex and Bison are included with the DJGPP distribution and 
    are also available on many archive sites.

II. To compile your copy of NetHack on a DOS machine:
    (or "just follow these few 'simple' steps outlined below.")

1.  It almost goes without saying that you should make sure that your tools
    are set up and running correctly.

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\msdos, util, win\tty and
    win\share.  Other subdirectories may also be included in your
    distribution, but they are not necessary for use with DOS.  You can
    delete them to save space.  If you are using MSC7 or MSVC, the makefile
    will create an additional working directory src\o.

    Required Source Directories for DOS NetHack:

                           (top)
                             |
        ------------------------------------------------- 
        |       |     |        |       |     |          | 
       util    dat   doc    include   src   sys        win
                                             |          |
                                          ------      ----- 
                                          |    |      |   |  
                                       share msdos   tty share

    Check the file "Files" in your top level directory for an exact
    listing of what files are 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 DOS.  Some programs have trouble
    with them, so you may need to convert them (with a utility like
    Rahul Dhesi's "flip").

3.  A few files in the NetHack distribution are uuencoded because
    they contain non-ascii characters, or binary information.  To use
    them they must first be decoded using a uudecode utility (available
    from your local archive site).  After reading the descriptions
    of these files below, uudecode the ones that you will need in order
    to build NetHack with the options that you have decided you want.

    The uuencoded files that are relevant to NetHack on a DOS machine
    include:

       nhico.uu   Optional.  This uudecodes into a MS-Windows compatible
                  ICON.  You only need to uudecode this if you plan on
                  launching NetHack from MS-Windows, and want a unique
                  Nethack ICON to use.

       nhpif.uu   Optional.  This uudecodes into a MS-Windows compatible
                  PIF file which may be used to launch NetHack from the
                  MS-Windows program manager.  You only need to uudecode
                  this if you plan on launching NetHack from within
                  MS-Windows.

       termcap.uu Optional.  Termcap support is no longer required for
                  building NetHack, though you can if you want to.
                  The file termcap.uu is the fixed version
                  of the Fred Fish termcap library.  If you have modified
                  pcconf.h to define TERMLIB as well as commented out
                  the default #define NO_TERMS, then you will need to
                  run a uudecode utility on termcap.uu to generate the
                  file termcap.zip.  termcap.zip contains several files
                  of termcap routines. Using them with NetHack involves
                  very little knowledge of the UNIX concept of a termcap
                  database; mostly you need to know enough to set a TERM
                  environment variable.  You can unzip termcap.zip in the
                  sys/share directory, but if you are going to use it, it
                  is probably better to unzip a copy in a special directory
                  and copy the library files to where your linker can find
                  them.  NetHack versions since 3.1.2 no longer enable
                  the use of termcap in the default configuration, or
                  with the official binaries.

                  Makefiles are included should you want to build your own
                  termcap library file.  Makemsc.lib works with Microsoft
                  C (MSC and MSVC) and generates termcap.lib, Makegcc.lib
                  works with DJGPP and generates libtermc.a.

4.  Go to the sys/msdos directory and ensure that the file setup.bat
    has MSDOS style end-of-line characters rather than UNIX style
    end-of-line characters.  You can do that using a utility like
    Rahul Dhesi's "flip", or by invoking the MSDOS edit utility on
    setup.bat and saving the file without making any changes. Failure to
    do this will prevent the bat file from executing completely, yet no
    warning message will be given.

    Run the setup.bat batch file with one of the following as the argument:

       MSC        For Microsoft C and its NMAKE.

       GCC        For djgpp and GNU MAKE.

       BC         For Borland C++ 3.1, and Borland's MAKE.

    The appropriate and necessary Makefile movements will be accomplished
    for you, as well as verifying a few files and fixing a few file names
    on FAT systems with long file name support.

5.  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,
    and check TERMLIB and COMPRESS.  Also be sure to leave DLB support 
    commented out in config.h.  MSDOS has support for DLB, but it must be 
    done through the Makefile, rather than config.h, to ensure that the 
    necessary packaging steps are done.

    We've managed to enable all the special features.  You may include all
    or as few of them as you wish.  To conserve disk space, you may wish
    to disable LOGFILE and NEWS.

    Also check pcconf.h, which should not need much editing (if you are
    including random.c, and if you do not require termcap for screen
    management).  If you are not including random.c you will need to
    comment out RANDOM.

    There are several options available for screen management with this
    release of PC NetHack.  The features #define TERMLIB, #define
    ANSI_DEFAULT, and #define NO_TERMS in pcconf.h control the various
    options.

    The NO_TERMS feature (the default) has the advantage of not needing a
    DEVICE=ANSI.SYS statement in config.sys.  The supplied sources and
    header files are distributed with support for NO_TERMS enabled.
    NO_TERMS will not work with TERMLIB, nor with ANSI_DEFAULT defined.
    The NO_TERMS feature uses internal routines for screen management, and
    may be an ideal choice if your play machine is industry standard (has
    an IBM compatible BIOS).

    Should you choose to leave NO_TERMS defined, define only one of the two
    screen access methods.  If compiling for Microsoft compilers, use
    SCREEN_BIOS; if using DJGPP, you can choose between SCREEN_BIOS
    and SCREEN_DJGPPFAST.  Never, never, ever choose both.  Bad things
    will happen.  We are not kidding.

    If you leave the #define TERMLIB commented in pcconf.h to disable use
    of termcap routines, then your screen management must rely on either
    the NO_TERMS feature described above, or the ANSI_DEFAULT feature.
    Either of these will make your job a bit easier than if you choose to
    use TERMLIB.  If you elect to include TERMLIB support, you may compile
    with both TERMLIB and ANSI_DEFAULT, and simply not set your TERM variable
    if you do not wish to use the termcap file settings.  You will need
    to uudecode the termcap library in sys\share if you are using the TERMLIB
    feature.

6.  If you want to change the high score list behavior, examine the top of
    topten.c, in the src directory.  You may want to change the definitions of
    PERSMAX, POINTSMIN, and ENTRYMAX.  We set POINTSMIN to 51 and ENTRYMAX to
    50 to keep the size of the score list down.

7.  Go to the src directory and edit the top of your Makefile.  Be sure the
    directory you want the game installed in (GAMEDIR) actually exists.

    If you elected to use termcap (TERMLIB defined), then uncomment the
    TERMLIB macro in your Makefile that points to the location of the
    library.

    That is,    TERMLIB =
    should be   TERMLIB = (SSYS)\termlib.lib

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

    a) For Borland C++ 3.1,

       Choose an overlay schema by setting SCHEMA to 1 or 2.  If you change
       the overlay schema, you will need to recompile all the object modules
       from scratch since the overlay schema is information is used during
       compile time for Borland C++, unlike Microsoft C which does it during
       link time.

    b) For Microsoft C 7.0 or greater, and Microsoft Visual C++

       The only overlay schema available is Schema3 so you don't have to 
       choose one.  The Makefile is set up for it already.  The overlay
       description file src\Schema3.def is created from sys\msdos\Schema3.MSC
       by setup.bat.

    If you elected to add graphical tile support, set TILESUPPORT to Y.

    Set USE_DLB to Y if you wish to place NetHack's many runtime files into
    a special archive that NetHack can utilize.  This is highly recommended!
    In fact, we haven't tested NetHack without it for several releases now.

8.  Now that everything is set up, what you do next depends on which
    compiler and version you are using.  You will need to execute either
    step 8a, or step 8b, or step 8c, but only one of them.

    a) For Microsoft C 7.0 or greater, and Microsoft Visual C++

       Go to the src directory, and "nmake install".

    b) For djgpp

       Go to the src directory, and using the GNU Make utility,
       "make install".

    c) For Borland C V3.1

       Go to the src directory, and using the Borland Make utility,
       "make -N install".


    Depending on your particular machine and compiler, you can either
    grab a cup of coffee or go home for the day.  Your computer will be
    occupied for quite some time.  If all goes well, you will get an
    NetHack executable.

9.  If you chose DLB support (recommended), make sure that the file nhdat 
    got copied into the game directory.

    If you didn't choose DLB support, make sure the support files --
    data, rumors, cmdhelp, opthelp, help, hh,history, guidebook.txt
    license, and all the *.lev files -- were copied to the game directory.  
    If not, move them there from the dat directory yourself.  rumors can 
    be created manually be entering "makedefs -r", data by entering 
    "makedefs -d".

    Make sure the files NetHack1.tib and NetHacko.tib made it to your game
    directory.  Copy them from src to the game directory yourself if
    necessary.

    Make sure the files defaults.nh and termcap made it to your game
    directory.  If not, go to sys\share and copy NetHack.cnf to
    your game directory as defaults.nh.  The name in previous versions was
    nethack.cnf, but the CNF extension conflicted with the MS Windows
    speed-dialer, making the file hidden on many machines.

    If you changed your build settings to include TERMCAP support, copy
    termcap to your game directory.  

    Also, make sure the file msdoshlp.txt made it to your game directory.
    If it didn't, move it from sys\msdos to your game directory
    yourself.

10. In your game directory, review the settings in defaults.nh and adjust
    them according to your style of play.  Some new options that you might
    be interested in are "menustyle" (for tailoring new object selection
    interface), and "video" (for turning on graphical tiles).

    On Borland C++, the soundcard:autodetect option enables pc speaker
    sound in NetHack if you compiled with PCMUSIC set in pcconf.h. It
    is rumored that this also works with djgpp, but the PCMUSIC setting
    in pcconf.h must be uncommented manually.

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

Appendix A - Building the "official binaries"

    If you wish to build a copy of NetHack identical to the ones that
    the pc team distributes, simply do the following:

1.  16-bit Real Mode Overlaid version
    Use the 16-bit  Microsoft Visual C++ V1.52c compiler

    Paths below are relative to the top of your unpacked
    NetHack source distribution:

       md \games\nethack
       cd sys\msdos
       setup MSC
       cd ..\..\src
       nmake install

2.  32-bit Protected Mode DPMI version
    Use the 32-bit djgpp compiler V2.03 or greater

    Paths below are relative to the top of your unpacked
    NetHack source distribution:

       md \games\nethackd
       cd sys\msdos
       setup GCC
       cd ..\..\src
       make install


Appendix B - Building other binaries

    Make sure that USE_DLB and TILESUPPORT (if using Microsoft C or Borland
    C) are both set to be turned on in the appropriate makefile.

    For an overlaid binary built with Microsoft C 7.00, make no changes to
    any of the defines and use the Makefile.MSC as distributed.

    For an overlaid binary built with Borland C++ 3.1, make no changes to
    any of the defines and use the makefile Makefile.BC as distributed.

    For the 32-bit binary built with DJGPP (playable on a 386 or
    better machine only), make no changes to any of the defines and use 
    the Makefile.GCC as distributed.

    Make sure the following files have been converted from the
    unix style "^J" end of line, to the msdos style "^M^J":
      license, help, hh, termcap, history, cmdhelp wizhelp and
      defaults.nh.

    Uudecode nhico.uu nhpif.uu.

    Place all the files in a clean directory and test.

Appendix C - Microsoft C Compilers

    Officially, support is no longer provided for MSC versions prior to
    7.0.  For versions of MSC 7.0 and greater (including Visual C++ ),
    a single Makefile is used, and it is MS NMAKE specific.  It is executed
    from the src directory.  It makes several passes over the files in order
    to produce overlays.

    MSC Version 7.0 works with or without the August 1992 patch.

    MSVC Professional 1.52c works as distributed.  In some rare cases
    you may encounter a problem with the compiler where it stops
    part way through the build with a memory error.  Things proceed
    normally after starting 'nmake install' once again.  The problem,
    although annoying if it happens, does not affect the code generation
    or the final executable.

    MSC Version 7.0 and MSVC take advantage of the CL environment variables
    to set the compiler flags, as they exceed the MSDOS limitation of 128
    characters on the command line.  Please read the Makefile carefully
    and select those options that go with the compiler.  The Makefile
    will set the CL environment variable within the context of the build,
    so you do not have to do it elsewhere.


  Microsoft C version 7.0 and
  Microsoft Visual C++ Professional versions up to 1.52c.

    Microsoft's MOVE overlay facility is suitable for building overlaid
    versions of NetHack.

    A single Makefile is used, and it is NMAKE specific.  It is executed
    from the src directory.  It is stored in the distribution as
    sys/msdos/Makefile.MSC.  It is moved to the src directory (with the
    new name 'Makefile') by setup.bat when invoked like so: "setup MSC".

    The Microsoft Visual C++ Professional compiler utilizes the same
    Makefiles and instructions for compiling as Microsoft C version 7.0.

Appendix D - DJGPP Compiler (gcc ported to msdos)

    If you have a 386 or better machine, you are in luck.  You can compile
    NetHack without spending money on a compiler.  DJGPP is available free
    from many archive sites.
    At the time of this release in August 2000, the URL
	http://www.delorie.com/djgpp/zip-picker.html/
    had information on how to obtain djgpp and what pieces to get.

    Setting up DJGPP is more than adequately explained in the documentation
    that comes with it.  Be sure to pick up the yacc and flex built with
    DJGPP if you intend to do any modification of the special levels or
    dungeon compilers.  They should be available at the same place you got
    djgpp.

    The latest version of djgpp, V2.03 will produce a binary that will run
    under Microsoft Windows, or any other DPMI provider.  djgpp also comes
    with a DPMI provider called CWSDPMI.  Place CWSDPMI.EXE in your path
    and it will be used in the absence of any other DPMI provider.

    If you want to use the built-in DJGPP screen routines, uncomment
    SCREEN_DJGPPFAST in pcconf.h (the default for djgpp).
    Note that some of these routines are broken under early versions
    of the compiler, so we pick and choose the ones that work.
    See video.c for details.

Appendix E - Borland C++ Compiler

    Officially, support is not provided for any version of Borland C++ or
    Turbo C++ other than Borland C++ 3.1.  It does not work with Borland
    C++ 4.5 yet, and versions 4.0 and 5.0 have not been tested.  We believe
    that compiling with the version of Turbo C++ equivalent to Borland C++
    3.1 should work.  For Borland C++ 3.1, a single Makefile is used, and it
    is specific to Borland's MAKE version 3.6.  It is executed from the src
    directory and makes several passes over the files in order to produce
    overlays.

  Borland C++ 3.1

    Borland's VROOMM overlay facility is suitable for building overlaid
    versions of NetHack.

    A single Makefile is used, and it is MAKE 3.6 specific.  It is executed
    from the src directory.  It is stored in the distribution as
    sys/msdos/Makefile.BC.  It is moved to the src directory (with the
    new name 'Makefile') by setup.bat.

    Remember to type 'make -N install' rather than just 'make install'.  The
    -N option is required.

    Make sure to set the directories BCTOP and related directories in
    Makefile. to the correct directory.  There are problems in running the
    newest versions of flex and bison from the all-purpose Makefile so you
    should leave DO_YACC and DO_LEX as is.

  Turbo C++

    As explained, this has not been tested.  However, if you want to test if
    Turbo C++ works, provided that the copy of Borland's MAKE you have is
    version 3.6 (you can check this by running MAKE in an empty directory),
    you are welcome to try.  If Turbo C++ does not define __BORLANDC__,
    just put the line:
	#define __BORLANDC__	__TURBOC__
    at the very very top of hack.h.  If it works, be sure to tell us.

Appendix F - Microsoft C Compiler Warnings

    If you are using MSC for your compile with any of the /W levels set,
    you can expect warnings.  The list below are those warnings that we
    are aware of and our recommendation for dealing with them.  You can
    use the warning disable pragma to ignore them if you wish.  (NOTE:
    this is not a complete list of all warnings you might receive, only
    those for which we feel we can safely provide guidance on.)

C4131 (function:uses old-style declarator)
    You should ignore this warning.  In order to make the source code as
    portable as possible, only old-style declarators are used so that as
    many compilers as possible can use the same code.
C4706 (Assignment within conditional expression)
    This is a perfectly valid construction.  These warnings have not
    produced any problems.
C4761 (Integral size mismatch in argument; conversion supplied)
    These should be no problem.  Prototyping compilers will do the con-
    version, and non-prototyping compilers will go through int anyway.

Appendix G - Additional Notes

1)  Save files and bones files from previous versions of NetHack will not
    work with this NetHack.  Don't bother trying to keep them.  Record
    (score) files from before 3.0 patchlevel 7 will almost work, but you need
    to make one change manually to them:  At the end of each line is a word or
    phrase specifying what killed the player.  Change the string to start with
    the words "killed by", "killed by a", or "killed by an" (whichever is
    appropriate).  If the death was petrification, it should read "petrified
    by" instead of "killed by".  Don't change "starvation", "quit", "escaped",
    or "ascended".

2)  To install an update of NetHack after changing something, type 'nmake'
    for Microsoft C, 'make -N' for Borland C++, and 'make' for DJGPP
    from the src directory.  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.  This is not officially
    supported for Borland C++.

3)  During linking the Microsoft Overlay Linker will need temporary storage
    space.  Make sure you have about a meg of free disk wherever you have
    defined your temporary storage.

Appendix H - Contacting the Development Team

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

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


