	SCCS Id: @(#)Install.dos	 3.1		93/07/07

        Copyright (c) NetHack PC Development Team 1990 - 1993.
       NetHack may be freely redistributed.  See license for details.
       ==============================================================
              Instructions for compiling and installing
                    NetHack 3.1 on an MS-DOS system
         ======================================================
                  (or, How to make PC NetHack 3.1)
                     Last revision: July 11, 1993

Credit for a runnable full PC NetHack 3.1 goes to the PC Development team
of Norm Meluch, Kevin Smolkowski, Paul Winner, Michael Allison and Steve
VanDevender who built on the work of Pierre Martineau, Stephen Spackman,
Steve Creps, Mike Threepoint and Don Kneller.

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 6.0a
    Microsoft C 7.0 and Microsoft Visual C++ Professional (MSVC) 1.0
    DJGPP       1.9 or later

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

    All the makefiles were created for use with NDMAKE.  The make programs
    provided by the various vendors all seem to lack necessary features,
    or differ enough in their syntax that the supplied makefiles won't
    work.  That is the case with 'nmake' supplied with the MSC compiler.  
    NDMAKE is available free from your local archive site.

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

    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 DOS.  Some programs have trouble
    with them, so you may need to convert them (with a utility like
    Rahul Dhesi's "flip").  Also, every file should end with an empty
    line, because both Microsoft C and MASM have a habit of ignoring the
    last line of each file. 

3.  The file termcap.uu is the fixed version of the Fred Fish termcap library.
    You will need to run a uudecode utility on it 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.

    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.

    Note that you only need the termcap library if you have changed 
    pcconf.h to define TERMLIB, and commented out the #define NO_TERMS 
    (See point 6).

4.  ovlmgr.uu (MS-DOS overlay manager) is the uuencoded assembled
    object module for the overlay manager used with Microsoft C 6.0
    and older.  This file is provided in case you do not have an assembler
    of your own.  You will need to run a uudecode utility on this file too,
    to generate ovlmgr.obj.  If you want to use this, put the ovlmgr.obj
    in the src directory; the makefile will access it when it needs it.

5.  Go to the sys/msdos directory and run the setup.bat batch file
    with either MSC or GCC as the argument.  The necessary Makefile
    movements will be accomplished for you.  In addition, when used
    with the MSC option, certain compiler options will be set.  Make
    sure that you either run setup.bat each time you start compiling
    or copy the line that starts "SET CL" into your autoexec.bat file.

6.  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,
    make sure the HACKDIR is set properly or disabled, and check TERMLIB
    and COMPRESS.

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

    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.  
    
    If you are using a Microsoft compiler you should make doubly certain
    that OVERLAY is defined in pcconf.h, since otherwise things will 
    compile properly but very ugly things are likely to happen wherever
    function pointers cross overlay boundaries - the linker is a little 
    thick about that.


7.  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.  I set POINTSMIN to 51 and ENTRYMAX to
    50 to keep the size of the score list down.

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

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

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

9.  Now that everything is set up, go to the util directory and
    run ndmake.  If you get any errors along the way then something
    has not been set correctly.  Next do the same in the dat directory.
    Finally, go to the src directory and "make 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 a long time.  If all goes well, you will get an NetHack executable.

10. Make sure the support files -- data, rumors, cmdhelp, opthelp, help, hh,
    history, and license -- 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 NetHack.cnf and termcap also made it to your game
    directory.  If not, go to sys\share and copy NetHack.cnf and
    termcap to your game directory.  Edit NetHack.cnf to reflect your
    particular setup and personal preferences, by following the comments.

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

    If you'll be running NetHack from a different subdirectory, you will
    want to "set HACKDIR=c:\games\nethack" (or whatever drive and directory 
    you want to use) now.  Add it to your autoexec.bat (in DOS), as you'll
    be playing often.

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

Appendix A - Building the "offical binaries"

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

    For the binary built with Microsoft C 7.00, make no changes to
    any of the defines.  

    For the 386 binary built with DJGPP, set the following
    - include/pcconf.h
      comment out #SCREEN_BIOS
      define SCREEN_DJGPPFAST

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

    Uudecode nhico.uu nhpif.uu.

    Place all the files in a clean directory and test.

Appendix B - Microsoft C Compilers

    You can compile NetHack using almost any version of Microsoft C later
    than 5.1, including Microsoft Visual C++ Professional 1.0.  MSC Versions
    5.0 and earlier are broken in such a way that it is impossible to use 
    them.  Version 6.0 requires a patch available from Microsoft; after 
    applying you should have 6.0ax.  
    
    MSC Version 7.0 works with or without the August 1992 patch. 

    MSVC Professional 1.0 works as distributed, although there seems 
    to be a problem with the compiler having problems and stopping the 
    compile periodically.  Things proceed normally after starting 'make'
    once again.  The problem, although annoying, does not affect the code
    generation or the final executable.

    Officially, support is no longer provided for MSC versions prior to
    6.0ax.  NetHack v3.1 will compile with 5.1, but you will need to
    make a lot of modifications to the makefiles in order to avoid heap
    space problems.  We strongly recommend upgrading to 6.0ax if you
    intend to recompile NetHack often.

    One Makefile is used for all versions.  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.  Also, remember to run setup.bat to set the
    CL environment variable before you compile.

    We use the following Makefiles:
    MakeMSC.src  - src directory
    MakeMSC.utl  - util directory
    Makefile.dat - dat directory

    The Makefile uses a structured break-up of the object modules so that
    we can link heavily used functions together without actual source code
    movement.  This has provided a great speed improvement for this release.
    See the file sys\msdos\ovlmgr.doc for more information on this
    structuring.

  Microsoft C version 6.0:
    The NetHack executable that you are about to get will be generated by an
    overlay linker.  The beauty of this overlay linker beastie is that it will
    create an executable that will function in much less memory than it would
    "normally" take to run.  Do not be deceived.  The RAM requirement for the
    overlay version is about 550k!  You can load the program in less RAM, but
    you will begin to experience a serious amount of disk thrashing at 530k
    or less.  Absolute minimum will probably be in the neighborhood of 380-400k.
    You do not want to run the program like that!  The more free RAM you have
    available for the program, the more smoothly it will run.

    Microsoft's internal overlay management scheme was pretty useless prior
    to version 7.0.  However, the sheer size of NetHack requires some sort
    of overlay scheme.  The magic piece to this puzzle is a program called
    ovlmgr.asm.  This is a replacement for the Microsoft (and we use the
    term loosely) overlay manager.  This program has been enhanced since
    its release in November 1989.  It will now allow NetHack to use EMS
    memory if any is available.  Also, the overlay manager will now read
    overlays out of files completely separate from the EXE.  This will
    cut down on the size of files for NetHack making distribution to PCs
    with low density disk drives much easier.

    If you have a MASM compatible Assembler, you may want to enable the option
    in the makefile to rebuild ovlmgr.obj, although a ready-made object file 
    is provided for those of you without.  Before assembling ovlmgr, be sure
    to read ovlmgr.doc as there are several options that you may or may not
    wish to enable/disable.

  Microsoft C version 7.0
    Microsoft was finally able to come out with a workable overlay
    linker in version 7.0.  Instead of linking in the custom overlay
    manager, we just let Microsoft do the work.

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

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

    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, 1.10, will produce a binary that will
    run under Microsoft Windows.

    If you want to use the built-in DJGPP screen routines, uncomment
    SCREEN_DJGPPFAST in pcconf.h.  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 D - Borland C Compiler

    NetHack will not compile at all with any version of Turbo C/C++.  It
    has been made to compile with Borland C v2.0 after much work, but the
    resulting binaries are far too slow to be playable.  It will not compile
    with Borland C/C++ v3.0 - the bugs in that version of the compiler
    related to the preprocessor make a total mess out of the macros that
    the NetHack code is laced with.  We haven't had much luck at
    compiling with v3.1 either.  If you successfully compile a playable
    binary using any version of Borland's compiler we would love to
    hear from you -- it would be a sure ticket to a position on the PC
    Development team and all the fame and fortune that goes along with
    it.  To get you started, here are a few hints.

    0. This should almost go without saying, but if you just bought
       Borland (or Turbo C) and you are thinking that compiling
       NetHack would be a great way to learn C and your nifty new
       compiler at the same time, you are either going to prove
       yourself some kind of prodigy or get very frustrated and quit.

    1. We left most of the __TURBOC__ defines in the code, some are
       necessary, others are not, and a few are misleading depending
       upon which compiler version you use as they relate to problems
       with Borland compilers long since fixed.  We left them in to
       provide some landmarks for future Borland hackers.

    2. No makefiles are provided as nothing we have tried has really
       worked.  Most of our attempts have started off using the
       GCC makefiles.

    3. Start off by working with the utility programs in the util
       directory.  They are the smallest and will give you some
       measure of success before you tackle the main code.  The
       programs contained in util are necessary to build the
       game so you will not be wasting your time.  Once you get
       the utility program compiled, run the makefile in the dat
       directory.  The utility programs you just compiled will attempt
       to convert the raw data files into game readable form.  If you
       get errors then something is wrong.

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


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, enter "make45l"
    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.

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.

4)  If you have comments or suggestions, feel free to drop any one of
    us a line c/o nethack-bugs@linc.cis.upenn.edu.  From compuserve,
    try INTERNET:nethack-bugs@linc.cis.upenn.edu.  Should you be
    without email access, some of us can still be reached by lesser means:

    For the west coast:
      Kevin D Smolkowski
      c/o OSLC
      207 E 5th
      Eugene, OR  97401

    Compuserve users can also reach Paul Winner by sending compuserve mail
    to 73207,226.  The NetHack binaries and sources can be found in the
    GAMERS forum.
