             Instructions for compiling and installing NetHack 3.3
                               on an OS/2 system
             =====================================================
                                Timo Hakulinen
                        Last revision: 29 October 1996

0.  Read this entire file before starting, and come back to the Notes below if
    you have any problems.

1.  Make sure all the NetHack files are in the appropriate directory
    structure.  You should have a top directory (e.g. nh33, or whatever you
    like) with subdirectories dat, doc, include, src, util, sys\share,
    sys\os2, and win\tty.  You may have other subdirectories under sys and
    win, but they will not affect compilation for an OS/2 system.  If you do
    not follow this structure, the makefile will not function properly.  The
    .c files for the main program belong in src, those for utility programs in
    util, and OS/2-specific ones in sys\os2.  All the .h files belong in
    include, the documentation in doc, and assorted data files in dat.  There
    are also some necessary files in sys\share (pc*.c, random.c, dgn_*.*,
    lev_*.*).  A more detailed explanation of the directory structure is found
    in file Files, which should be in the top directory.

    If you downloaded or ftp'd the sources from a UNIX system, the lines may
    end in UNIX-style newlines instead of the carriage return and line feed
    pairs used by DOS and OS/2.  You'll have to convert them (with a utility
    like Rahul Dhesi's "flip").  Also, every file should end with a carriage
    return / line feed pair, because Microsoft C has had a habit of ignoring
    the last line of each file otherwise.  Besides, even editing UNIX-style
    files with DOS editors is often a royal pain.

2.  The makefile for OS/2, Makefile.os2, is found in directory sys\os2.  Copy
    it to directory src and rename it Makefile.  From now on, Makefile.os2
    will be referred to as "the makefile" in this document.

    The makefile supports the following make utilities:

    NDMAKE      a public domain make utility for DOS by Don Kneller
    NMAKE       make shipped with Microsoft languages and IBM C Set/2
    DMAKE       a public domain make for DOS and OS/2 by Dennis Vadura

    Both NDMAKE and DMAKE are available at major archive sites.  The
    following compilers are supported:

    compiler:                           runs in:            compiles for:

    Microsoft C 5.1                     DOS / OS/2 1.0-Warp OS/2 1.x
    Microsoft 6.0A (see note 5)         - " -               - " -
    IBM C Set/2 1.00, Toolkit/2 2.00    OS/2 2.x, Warp      OS/2 2.x, Warp
    IBM CSet++ 2.00                     OS/2 2.x, Warp      OS/2 2.x, Warp
    GCC emx 0.8f (see note 6)           OS/2 2.x, Warp      OS/2 2.x, Warp

    Note that code compiled for OS/2 versions 1.0-1.3 runs unmodified in OS/2
    versions 2.0 and up.  In principle it should be possible to cross compile
    NetHack 3.3 for OS/2 in DOS using NDMAKE and MSC, but this is not
    recommended (see note 3).

    If you're using some other compiler than one listed above, you will have
    to adapt the makefile to your needs.  In particular, change the CC,
    CFLAGS, LINK, and LFLAGS macros to your C compiler's and linker's liking.
    See the makefile for more information.

    If you are going to be constructing Fred Fish's termcap library, you'll
    need Makefile.lib in sys\share (see note 4).

3.  Go to the include subdirectory.  First edit config.h according to the
    comments to match your system and desired set of features.  In particular,
    make sure that OS2 is defined, and that UNIX, HACKDIR, and COMPRESS are
    *not* defined.  If you want to try out the new DLB data file library
    scheme, uncomment DLB.  Note that although the makefile contains some
    support for this scheme, it's new in NetHack 3.3 and hasn't been tested.
    If your compiler is ANSI compliant (like practically all OS/2 compilers
    are), it's probable that nothing else needs to be configured in config.h.

    Next look at os2conf.h.  This file shouldn't need much changing.  If you
    want to use the hardcoded OS/2 system definitions in def_os2.h instead of
    the compiler's standard headers, comment out OS2_USESYSHEADERS.  This may
    become necessary if you are using a compiler which doesn't come with
    proper system headers by default.  In this case you may have to edit the
    definitions there, because every compiler has its own way of declaring
    the necessary system functions and data structures.  In general you
    should prefer the compiler's offerings, if possible.

    If you are going to compile the game on an HPFS drive, uncomment OS2_HPFS,
    which enables the use of longer file names during compilation.  The
    generated executable will only use file names compatible with FAT drives,
    however.

    If you are using a 32 bit compiler other than GCC emx 0.8f or C Set/2 in
    OS/2 2.x, force OS2_32BITAPI to be defined.  Otherwise it is defined only
    for the above mentioned compilers.

    If you are not going to include random.c, because you are using the
    random number generator provided by your compiler, you will need to
    comment out RANDOM.

    If you want to muck with different termcap settings, uncomment TERMLIB to
    enable the use of termcap routines (see note 4).  This is not necessary to
    create a fully functional game, however.

4.  If you are using another compiler than MSC, GCC, or IBM C Set/2, you may
    want to look through system.h in the include directory.  This file matches
    the return and parameter types for system calls and library routines with
    various flavors of compilers and operating systems.  Leaving this file
    alone is unlikely to cause problems, but if you get compile errors with
    any functions in the standard library, it's worth checking the
    declarations there.

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

6.  Go to the src directory and edit the top of the makefile.  Be sure that
    the directory you want the game installed to actually exists.

    You'll need nroff and/or TeX/LaTeX to do the files in doc.  If you don't
    have either of these, you can skip it.

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

    If you elected to use Fred Fish's termcap library (bundled in as
    termcap.uu in directory sys\share), you will have to generate termlib.lib
    from those sources by typing "make -f makefile.lib termlib.lib".  You must
    set the TERMLIB option in the makefile to link the resulting termlib.lib
    into the game.

    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 time stamps fool make.

    If you have lex and yacc programs, or the equivalent flex and bison
    programs, you can set up the makefile to generate the appropriate .h and
    .c files from their .l and .y counterparts whenever you recompile.  This
    is done by changing the do_yacc and do_lex targets in the makefile to
    depend on targets yacc_act and lex_act instead of yacc_cpy and lex_cpy.
    Otherwise the makefile will copy pre-generated yacc and lex output files
    dgn_*.* and lev_*.* from directory sys\share to util and include.

    Now, enter "make all", and take a siesta; your computer will be occupied
    for a fair amount of time.  If all goes well, you will get an executable.

7.  All the support data files should have been copied to the game directory
    by the make process.  Here is the complete list in alphabetical order of
    all the files that should have gotten there during a full build:

    Arc-fila.lev   Arc-filb.lev   Arc-goal.lev   Arc-loca.lev   Arc-strt.lev
    Bar-fila.lev   Bar-filb.lev   Bar-goal.lev   Bar-loca.lev   Bar-strt.lev
    Cav-fila.lev   Cav-filb.lev   Cav-goal.lev   Cav-loca.lev   Cav-strt.lev
    Hea-fila.lev   Hea-filb.lev   Hea-goal.lev   Hea-loca.lev   Hea-strt.lev
    Kni-fila.lev   Kni-filb.lev   Kni-goal.lev   Kni-loca.lev   Kni-strt.lev
    Mon-fila.lev   Mon-filb.lev   Mon-goal.lev   Mon-loca.lev   Mon-strt.lev
    Pri-fila.lev   Pri-filb.lev   Pri-goal.lev   Pri-loca.lev   Pri-strt.lev
    Ran-fila.lev   Ran-filb.lev   Ran-goal.lev   Ran-loca.lev   Ran-strt.lev
    Rog-fila.lev   Rog-filb.lev   Rog-goal.lev   Rog-loca.lev   Rog-strt.lev
    Sam-fila.lev   Sam-filb.lev   Sam-goal.lev   Sam-loca.lev   Sam-strt.lev
    Tou-fila.lev   Tou-filb.lev   Tou-goal.lev   Tou-loca.lev   Tou-strt.lev
    Val-fila.lev   Val-filb.lev   Val-goal.lev   Val-loca.lev   Val-strt.lev
    Wiz-fila.lev   Wiz-filb.lev   Wiz-goal.lev   Wiz-loca.lev   Wiz-strt.lev
    air.lev        asmodeus.lev   astral.lev     baalz.lev      bigrm-1.lev
    bigrm-2.lev	   bigrm-3.lev    bigrm-4.lev    bigrm-5.lev    castle.lev
    cmdhelp        data           dungeon        earth.lev      fakewiz1.lev
    fakewiz2.lev   fire.lev       help           hh             history
    juiblex.lev    knox.lev       license        medusa-1.lev   medusa-2.lev
    minefill.lev   minend-1.lev   minend-2.lev   minetn-1.lev   minetn-2.lev
    nethack.cmd    nethack.cnf    nethack.exe    nethack.ico    opthelp
    options        oracle.lev     oracles        orcus.lev      quest.dat
    recover.exe    rumors         sanctum.lev    soko1-1.lev    soko1-2.lev
    soko2-1.lev    soko2-2.lev    soko3-1.lev    soko3-2.lev    soko4-1.lev
    soko4-2.lev    tower1.lev     tower2.lev     tower3.lev     valley.lev
    water.lev      wizard1.lev    wizard2.lev    wizard3.lev    wizhelp

    Yes.  It's 112 files for a full featured NetHack 3.3.  If any of the files
    are missing, try to rerun make.  If that doesn't help, you'll have to try
    to decipher the makefile to find out how to manually create the missing
    files.  These kinds of troubles shouldn't happen except for two reasons:
    You've run out of disk space while compiling or your make utility doesn't
    understand the makefile properly for some reason.  In either case, you
    should get some warnings from the make, though.

    If you have old record, logfile, or news files in the game directory, they
    are not overwritten.  Of course, old records from NetHack 3.1 and 3.2 are
    not worth keeping with 3.3, since these games are really quite different.

    Edit file nethack.cnf in the game directory to reflect your particular
    setup and personal preferences, following the comments there.  More info
    about settable options can be found in the file opthelp and the guidebook.

    If you compiled in the TERMLIB feature, also move the sys\share\termcap
    file to your game directory.

8.  If you'll be running NetHack from a different subdirectory, you will want
    to "set HACKDIR=c:\games\nh33" (or whatever directory you want to use).
    Add it to your config.sys, if you'll be playing often.

    You can also create a special NetHack entry in your Presentation Manager /
    Workplace Shell desktop.  This will use the included NetHack icon.
    The following is a sample program description for OS/2 1.3 desktop, but
    it's similar for OS/2 2.0:

    Program title:          NetHack 3.3
    Path and file name:     c:\games\nh33\nethack.cmd
    Parameters:
    Working directory:      c:\games\nh33
    Program type:           OS/2 Full screen

    Naturally you must fill in your own game directory and parameters if you
    want to set any.  The program type can be either OS/2 Full screen or OS/2
    Windowed.  Note that you should set the executable path to use the .cmd
    file generated by the makefile.  This file generates an extra pause after
    the program exit, because otherwise you wouldn't get to see the high score
    list upon quitting due to PM/WPS automatically closing the program window.
    When starting NetHack normally from OS/2 command prompt, the command
    processor starts nethack.exe instead, so no extra pause is generated.

9.  If you want to clear up the temporary files and objects created by the
    compilation process, you may issue "make spotless".  This will return your
    source tree to near-distribution condition.  Naturally, it will not affect
    your newly built game files in any way.

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


Notes
-----

1)  Save-files and bones-files from previous versions will not work with
    NetHack 3.3.  Don't bother trying to keep them.

2)  To install an update of NetHack after changing something, enter "make"
    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.)

3)  When cross-compiling for OS/2 in DOS, NDMAKE is the best choice because it
    requires the least RAM for itself.  Note however, that cross-compilation
    in DOS is discouraged, because it is considered obsolete (OS/2 is really
    a much better place to compile).  If you still want to try, here are some
    suggestions:

    During linking, Microsoft linker will need temporary storage space.  Make
    sure you have about 1 MB of free disk where ever you have defined your
    temporary storage.  It is also a good idea to compile with as much free
    RAM as possible.  It may otherwise get crowded with the bigger, more
    complex source files (compiler bombs with "out of heap space" or similar).
    If this happens, strip your configuration, zap TSR's, get a better memory
    manager etc.

4)  The file sys\share\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 best
    to unzip a copy in the src directory.  That way you will not miss copying
    any files over.  Wherever you unzip it, get rid of the included makefile
    since a better version has been provided as Makefile.lib.  After creating
    the termcap library file termlib.lib, copy it to src before compiling the
    game main source.

5)  When compiling with MSC 6.0, the maintenance version 6.0A should be used
    instead of the original 6.0, which was all too buggy to successfully build
    NetHack.

6)  Note that emx 0.8f is the first version of GCC for OS/2 that can properly
    compile NetHack.  Earlier versions do not work, because they don't support
    the 16 bit API calls of OS/2.

    GCC emx 0.8f does not currently work properly when fseek() function is
    used with text files.  This is well documented in the compiler's
    documentation.  Unfortunately NetHack uses fseek() in several places in
    connection with text data.  This means that some help texts may not come
    out right, but no serious problems should emerge.
