nethack/sys/unix/Install.unx

                Instructions for installing NetHack 3.5
                           on a UNIX system
                =======================================

0.  Read this entire file before starting, and come back to the Notes
    below if you have any problems.  If you are trying to use X11,
    also read all of win/X11/Install.X11, or read win/Qt/Install.Qt
    if you are using Qt or KDE under X11.  For help in controlling
    and running the game after it is installed, see the '?' command
    within the game and doc/Guidebook (non-installers want to know
    about those things too).

1.  Make sure all the NetHack files are in the appropriate directory
    structure.  You should have a main directory with subdirectories
    dat, doc, include, src, util, sys/share, sys/unix, win/tty, win/X11,
    and win/Qt.  You may have other subdirectories under sys and win,
    but they will not affect compilation for a UNIX system.  If you do
    not follow this structure, the Makefiles will not function properly.
    The .c files for the main program belong in src, those for utility
    programs in util, and UNIX-specific ones in sys/unix.  All the .h
    files belong in include, the documentation in doc, and assorted
    data files in dat.  Some UNIX versions may also be interested in
    sys/share's random.c or its lex/yacc output, as explained in note 11.
    (A more detailed explanation of the directory structure may be found
    in Files, which should be in the top directory.)

2.  Your Makefiles may still be in sys/unix with tags on the end of them.
    If so, run "sh setup.sh hints/unix" in that directory to
    distribute the Makefiles to places they can do their work.  (If
    later official patches change these Makefiles, setup.sh should
    be rerun to make sure you use the current copies.)

3.  Go to the include subdirectory and edit config.h according to the
    comments to match your system and desired set of features.  Similarly
    edit unixconf.h.  Please see the "Notes:" section, below, for some
    configuration hints for particular systems.

4.  If you want to, look through system.h.  This file attempts to match the
    types for system calls and library routines with various flavors of
    operating systems.  Leaving this file alone is unlikely to cause worse
    problems than lint errors, but it's worth checking if you get compile
    errors, especially if you have an unusual system.

5.  Go to the src subdirectory and look at the top of topten.c.  You may want
    to change the definitions of PERSMAX and PERS_IS_UID here to get different
    behavior from the high score list.

6.  Edit the top sections of the src and util Makefiles.  (If you are doing
    a full recompile, or if you got your files from someplace besides the
    official distribution, type 'touch makedefs.c' to make sure certain files
    (onames.h, pm.h) get remade instead of relying on the potentially
    troublesome timestamps.)  Then type 'make' in src and go get a cup of
    coffee or take a nap, depending on the speed of your system.  You should
    now have created the game executable.

7.  Go back to the top directory and edit that Makefile, explaining where
    you want everything to be installed.

    Make sure that you follow the comments about setting HACKDIR -- the
    installation process will wipe out the contents of the directory you
    point it at, under the assumption that it's debris from an old version
    of NetHack.  If this is not the case, you'll want to install somewhere
    else, or comment out the rm under the install target.

    The Makefile assumes you want to run NetHack setuid 'games' to cut down
    on possible tampering; it's fairly straightforward to comment out the
    appropriate chmod if you don't want that, or to change any of the rest
    of the procedure.  (Note that if you don't want to run NetHack either
    setuid or setgid, and people in more than one group will be playing it,
    you'll need to go back and set FCMASK to 0666 in unixconf.h and let
    everybody fiddle with the files NetHack creates.)

    If the tbl, nroff or col commands are not available on your system,
    edit the doc/Makefile and change the GUIDECMD as directed.

    Type 'make all' from the top directory to set up all the auxiliary
    files the main executable will use.  Then become root if necessary and
    type 'make install'.  Everything should now be set.

8.  Read doc/recover.man or doc/recover.txt to learn how to use the recover
    program.  The recover program can be used in case of a crash to recover
    a game that was in progress.  The recover command is installed in the
    HACKDIR by default.

Notes:

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

2.  To install an update of this version of NetHack after changing something,
    type 'make update' from the main directory.  If you created the new
    version yourself, it should be safe to use 'make update' as long as you
    did not add, delete, or reorder monsters or objects and you did not change
    the format of saved level files.  If you did any of these things, you
    should also remove any saved games and bones levels.  (Trying to use such
    files often produces amusing but useless confusions on the game's part.)

3.  If you insisted on doing the final installation by hand, you probably
    forgot to make a save directory.  If you don't go back and do this, you
    won't be able to save games.

4.  If you get unexplained deaths by trickery, you are probably running
    NetHack on a bunch of workstations, but you have overlooked the NETWORK
    definition in unixconf.h that is necessary in that configuration.

5.  If spurious characters appear on the screen while throwing, kicking,
    zapping, etc., it is likely that you have linked the source to the wrong
    library or mistakenly defined/undefined TERMINFO.  A number of systems,
    such as Xenix, support both the termcap and terminfo terminal capability
    libraries.  In such cases, the TERMINFO definition in unixconf.h and the
    WINTTYLIB definition in the source Makefile must correspond.

    If your terminal library does not provide suitable delays, NetHack will
    try to fake its own if you set the nonull option.

6.  Since NetHack overflows the stock C preprocessors for AT&T 3b1 and 3b2
    systems ("too many defines"), we are including an alternate preprocessor
    to allow these folks to compile.  This is the DECUS cpp by Martin Minow,
    slightly modified by Kevin Darcy to use larger buffers, be less verbose,
    and handle strange constructs in AT&T's include files.

    To use this preprocessor, unpack the cpp* files found in sys/unix into
    some handy directory (util will do).  For the AT&T machines mentioned
    above, nothing needs to be configured; you should get a working cpp by
    merely typing "make -f makefile.txt".  To get your compiler to use the
    new cpp, you will have to add to CFLAGS in src/Makefile and util/Makefile.
    If you put the cpp files in /foo/bar/util, add "-B/foo/bar/util/ -tp"
    for a 3b1 or "-Yp,/foo/bar/util" for a 3b2.

    For any other machine whose preprocessor can't handle the NetHack source,
    you'll have to play it by ear.  The preprocessor has many esoteric
    configuration options, but most probably you will only need to change
    the flags in makefile.txt, and then refer to your compiler's documentation
    to find the appropriate CFLAGS for the NetHack Makefiles.  (The SunOS flag,
    for instance, would be "-Qpath /foo/bar/util", although the native cpp
    has no trouble with NetHack.  So much for standardization.)

7.  If you are trying to compile NetHack on an AT&T 3B that is running an
    OS earlier than SVR3, you are likely to have problems with overflowing
    symbol tables.  This can be worked around by editing the source Makefile
    to make the Sys.3B2 target work more like the SysV-AT target, adding
    -DDUMB to CFLAGS and DUMB.Setup to the Sys.3B2 dependency line.  The
    compiler provided with later versions of the OS has a large enough
    symbol table that it does not need this workaround.

8.  If NetHack seems to compile fine, starts up, allows you to pick a
    character, and then hangs indefinitely, gets a segmentation fault, or
    traps you in a single room on the first level, you might try changing
    the schar and uchar definitions in config.h to short ints.  This problem
    is known to occur on the AT&T 3B series, Silicon Graphics Irises, and
    IBM systems (PC/RT & RS/6000) running AIX, and may occur on other
    computers as well.

    This problem is really most likely caused by having a non-__STDC__
    compiler with char's unsigned by default.  Since some such compilers
    don't understand the new "signed" keyword, and others don't have signed
    characters to use (the 3B2 line falls into this category), "signed"
    is #ifdefed away for them.  If you are sure your compiler can deal
    with it, you can add your compiler to the __HC__ case in tradstdc.h.

    Alternatively, if the compiler supports a command line switch for
    setting the default char type to signed, you could try setting it in
    the Makefiles.  The appropriate switch for SGI Irises with MIPS C
    compiler is "-signed" and for RS/6000's with standard cc "-qchars=signed".
    (SGI machines running IRIX 4.0.x have a compiler close enough to
    standard to suit NetHack, so you may merely use the suggested flags
    in the Makefiles.)

    Note that at least RS/6000's seem to like changing the default to
    signed better but there is also a problem:  The lexers created by
    the standard lex program in AIX may come out faulty when this switch
    is used (known to happen at least in AIX 3.1.3), so you may have to
    use an alternative, like flex, which is available at major archive
    sites (see notes 10 and 11).

    By AIX 3.2.5, this whole problem should be taken care of automatically
    (but AIX_31 should still be defined in unixconf.h for other reasons).

9.  Under SCO UNIX, you may have all sorts of complaints about
    include/obj.h.  Go to the file and uncomment the marked line, working
    around the fact that SCO's system include files preempt a major
    NetHack structure name.  Also, there are difficulties with SCO's cc
    that thus far have been solved only by changing compilers; one report
    says gcc-NetHack works, and another says rcc-NetHack can be made to
    work by defining NOTSTDC, applying note 8, and compiling with -tinfo
    and -xenix.  The cc problems are old enough that a new, working
    version may have been released by this time.

10. Xenix/286's lex generates a faulty lexical analyser from lev_comp.l.
    The beta-release of flex 2.3 (available from uunet, osu-cis,
    prep.ai.mit.edu, etc.) can be used to generate the lexer.
    The only change to flex is to change "#define yyleng (yy_cp - yy_bp)"
    to "#define yyleng (int)(yy_cp - yy_bp)" in flex.skel.
    Flex is not needed with Xenix/386, as its lex generates a proper lexical
    analyser.  [Xenix instructions by J.T. Conklin]

11. If your system does not have a lex/yacc or flex/bison combination
    capable of producing the dungeon and level compilers, lex and yacc
    output from one of our development systems can be found in sys/share.
    Unfortunately, this output is less portable than the rest of the code,
    as it contains skeleton parsing code provided by the specific vendor
    who has no particular incentive to make such skeletons portable, but
    the output works on most systems.  To try it on yours, copy dgn_comp.h
    and lev_comp.h to include and dgn_lex.c, dgn_yacc.c, lev_lex.c, and
    lev_yacc.c to util.

12. Yes, Virginia, you compile NetHack for a NeXT as if it ran UNIX instead
    of Mach.  Just tell NetHack you're a BSD system (Mach is extremely
    close to BSD UNIX for traditional system calls, so this is also a
    likely thing to try for any other programs you want to compile).

    If you get errors when starting nethack warning that "Setuid execution is 
    not allowed", you might want to re-install using the setgid option instead
    (see Note 7 above, and the setgid comment in the toplevel Makefile).

13. If you are using Solaris 2.x (aka SunOS 5.x) you shouldn't have to
    do any system configuration -- this is the default.  In case it is
    messed up, follow these instructions.

    Solaris is basically a SVR4 system, not a BSD system.  Therefore, you
    configure config.h and unixconf.h as per a SVR4 system:

	config.h: UNIX, TTY_GRAPHICS
	unixconf.h: SYSV, SVR4, TERMINFO, POSIX_JOB_CONTROL, POSIX_TYPES

    X11_GRAPHICS does work.  Do not define OPENWINBUG.  You may safely define
    NETWORK, TEXTCOLOR if desired.  Other #defines in these files may be
    defined too, as needed.  Just make sure that the set mentioned here are
    not misdefined, or your compile will fail (do _not_ define BSD or SUNOS4).
    Unless you are using gzip you will probably want to define COMPRESS to
    be "/usr/bin/compress".

    When compiling, make sure that you use the ANSI C SVR4 compatible
    compiler, /usr/bin/cc, or gcc, but _not_ ucbcc.  The lattermost will
    not work.  After this, you should get a clean compile.

    Also, it is recommended that you use FLEX instead of the standard
    lex bundled with Solaris 2.x (even if that last one should work ;-).

14. If your machine is a 286, 386, or 486 running an appropriate OS, you
    may wish to use the console speaker driver included in
    sys/unix/snd86unx.shr.  This will allow audible music to be played
    on your console speaker in certain appropriate game situations.  The only
    modification to the main-line code needed to enable use of the driver
    is defining UNIX386MUSIC or VPIX_MUSIC in unixconf.h.

15. If you are trying to cross-compile for another system, there is some
    support in the src and util Makefiles, but there are still other
    complications.  It may well be best to make another copy of util,
    util2, to compile target copies of makedefs, lev_comp, and recover
    (duplicating the cross-compilation settings from the src Makefile)
    without disturbing the main build.

    You can use the host makedefs for everything but "makedefs -v", which
    creates include/date.h, which provides various sanity-checking values
    for making sure files read by NetHack at run-time are compatible.
    These values depend on the endianness of your processor, its type
    sizes, and its compiler's idea of struct packing.  Your host and target
    computers may disagree on these things, so you'll need to build a target
    version of makedefs, run "makedefs -v" on your target, and bring the
    resulting date.h back for the builds on the host.  (Making sure the host
    makedefs doesn't decide it needs to overwrite it for you. :-)

    You also need a target version of lev_comp, and to provide it with all
    the dat/*.des files, and copy all the resulting *.lev files back for
    packaging on the host.

    For recover, you just want the target binary to install on the target.