Using, Compiling, and Installing Amiga NetHack 3.1 (or Everything You Never Wanted to Know Before NetHacking) Last Revision: 12 January 1993 for NetHack 3.1 I. Introduction I.A. Overview Welcome to Amiga NetHack! If this is your first visit to our fair city, you are in for an amazing and dangerous journey; if you have visited us before, beware! the city has changed in many strange and subtle ways; it has also grown quite a bit. This missive brings to light those mundane tasks which must be dealt with before beginning your journey; for those of you who are faced with the task of installing the pre-fabricated version of our town, section III (Installing Amiga NetHack 3.1) will guide you through the task at hand. If you are ready to visit, the local visitors guide is in section II (Using Amiga NetHack 3.1); please also see the general guide packaged separately (the file GuideBook). Finally, for those brave souls among you who prefer to scratch-build your own models, your guidance is in section IV (Compiling Amiga NetHack 3.1). To all our visitors, a hearty Welcome! - and please be careful. [Those responsible for the previous paragraphs have been sacked. The documentation has been completed at great expense in a more traditional style. -- The Management] I.B. Getting Help If you have questions about strategy, weapons, or monsters, the best place to go for help is the Usenet newsgroup rec.games.hack. If you have problems with installation or think you have found a bug in the game, please report it by electronic mail to the development group at nethack-bugs@linc.cis.upenn.edu, where it will be routed to the appropriate person. Include your configuration, the version of NetHack you are playing, and as much specific information as possible. As NetHack runs on many different machines, be sure to mention that you are playing the Amiga version. Finally, if you are having trouble compiling NetHack, you may use the same address, or, for compiler specific problems, send mail to: Greg Olson (golson@sundown.sun.com) for Manx Ken Lorber (keni@oasys.dt.navy.mil) for SAS/C, or Richard Addison (addison@pollux.usc.edu) for either. We do not currently have a contact for the DICE port. I.C. Credits Olaf Seibert first ported NetHack 2.3 and 3.0 to the Amiga. Richard Addison, Jochen Erwied, Mark Gooderum, Ken Lorber, Greg Olson, Mike Passaretti, and Gregg Wonderly polished and extended the 3.0 and 3.1 ports. II. Using Amiga NetHack 3.1 II.A. Sources of Information Where to go depends on what you want to find out. If you want to find out about distributing NetHack, read the license (in NetHack:license or type ?i during the game). For an introduction to NetHack, read the GuideBook file. Finally, for information during the game on all kinds of things, type ? and select from the menu. II.B. The Amiga NetHack WorkBench Front End The Amiga NetHack Front End looks more or less like a WorkBench Drawer - and acts the same way. Games start with double clicks and menus provide more detailed control of games and defaults. On-line help is available - just press the help key. Just as with WorkBench itself, options for games are set using the Info menu item to modify Tooltypes. Most common options can be set more easily using buttons available via Info also. You can adjust the following using the ToolTypes from the Info command: * OPTIONS= - Options as available in the NetHack.cnf file. * HACKDIR= - Set NetHack working directory to be this directory. * LEVELS= - Intermediate level saving device/directory. * PATH= - To search for files such as rumors, help, etc. * CMDLINE= - Arguments as passed on the CLI command line. Note: only the following flags are valid: n, X, D, and r. * SCORE - Display the record of scores. Options as available on the CLI command line after a -s flag. Note that the NetHack.cnf file is read first, then the ToolTypes. This means that the options specified in the NetHack.cnf act as defaults which can be overridden by an individual's personal icon's ToolTypes. Thus the system oriented entries (HACKDIR, LEVELS, and PATH) should generally be set only in NetHack.cnf. NetHack.cnf should have default values for OPTIONS, which will generally be overridden by ToolTypes entries. Also, there is one additional option that may be specified in the NetHack.cnf file or on an OPTIONS line: flush. When enabled, flush discards all characters in the queue except the first, which limits typeahead accidents. The default setting is noflush. Usually, most of the confusing options will be set in the NetHack.cnf file once when the game is installed and can be ignored after that. II.C. The Amiga NetHack CLI Front End The CLI Front End provides the standard Unix-like command line interface to NetHack. Unlike the Unix front end however, the CLI front end will ask if you want to play again before exiting. See the ManPage file for the standard Unix flags for NetHack. In addition to those flags, Amiga NetHack accepts flags -l to force non-interlaced mode and -L to force interlaced mode. III. Installing Amiga NetHack 3.1 III.A. General Installation Installation should be easy - basically it consists of putting files where they belong and adding assigns to your startup. If you are installing from the official binary distribution, simply unpacking each archive in the appropriate directory will put the files in the places they belong (note that the archives may have been split for distribution). If you are installing from source, most of this work will be done by the time the build is finished. IF YOU ALREADY HAVE A PREVIOUS VERSION INSTALLED YOU MUST DELETE THE OLD SAVE AND BONES FILES - THEY WILL NOT WORK! Will NetHack fit on your machine? NetHack 3.1 is large. NetHack 3.1 is very large. You will need: > Amiga 500, 1000, 2000, 2500, or 3000. The A600, A1200, and A4000 should work, but have not been tested. > WorkBench 1.3 or 2.04. WorkBench 1.2 will NOT work; we will NOT be fixing that. WorkBench 2.1 and 3.0 should work but have not been tested. > At least 2 meg of RAM. NetHack will NOT run in 1 meg. > Mass storage: NetHack will run on one floppy - but it won't be nice. Two floppies are almost enough. A hard drive with over 3 meg of free space is recommended. Find space for the files Floppy installation: Format four disks named: NetHack HackExe NHsave NHlevels Hard Disk installation: cd to wherever you want to install NetHack makedir NetHack makedir NetHack/save makedir NetHack/levels In s:User-Sequence (under 2.0 or later) or s:Startup (under 1.3), assign NetHack: to the NetHack directory you created above. assign HackExe: to the same directory. Install the files Unpack the archives in the directories or onto the disks (you can tell what to unpack where by the file names). Use the table in the next section to see where things should end up. Be sure that the file 8 ends up in NetHack:hack/8. Configuration Using your favorite text editor, edit NetHack:NetHack.cnf to match your system. Check HackExe:NetHack.dir and be sure that the paths are correct. The HackWB program uses several standard Amiga programs that must be installed in their standard places: c:copy, c:rename. III.B. File Location Table NetHack: A-filla.lev A-fillb.lev A-goal.lev A-locate.lev A-start.lev air.lev asmodeus.lev astral.lev B-filla.lev B-fillb.lev B-goal.lev B-locate.lev B-start.lev baalz.lev bigroom.lev C-filla.lev C-fillb.lev C-goal.lev C-locate.lev C-start.lev castle.lev cmdhelp data default.icon dungeon E-filla.lev E-fillb.lev E-goal.lev E-locate.lev E-start.lev earth.lev fakewiz1.lev fakewiz2.lev fire.lev Guidebook Guidebook.info H-filla.lev H-fillb.lev H-goal.lev H-locate.lev H-start.lev hack/8 hack.font HackWB HackWB.info HackCli help hh history juiblex.lev K-filla.lev K-fillb.lev K-goal.lev K-locate.lev K-start.lev knox.lev license logfile ManPage ManPage.info medusa-1.lev medusa-2.lev minefill.lev minetown.lev mine_end.lev NetHack.cnf NetHack.c01 NetHack.d00 news NewGame.info opthelp options oracle.lev oracles orcus.lev P-filla.lev P-fillb.lev P-goal.lev P-locate.lev P-start.lev perm quest.dat R-filla.lev R-fillb.lev R-goal.lev R-locate.lev R-start.lev ReadMe ReadMe.info record recover rumors S-filla.lev S-fillb.lev S-goal.lev S-locate.lev S-start.lev sanctum.lev T-filla.lev T-fillb.lev T-goal.lev T-locate.lev T-start.lev tower1.lev tower2.lev tower3.lev V-filla.lev V-fillb.lev V-goal.lev V-locate.lev V-start.lev valley.lev W-filla.lev W-fillb.lev W-goal.lev W-locate.lev W-start.lev water.lev wizard1.lev wizard2.lev wizard3.lev wizhelp HackExe: NetHack.dir NetHack.c00 IV. Compiling Amiga NetHack 3.1 IV.A. Compilation Overview Compiling NetHack is not very hard - basically you do a little configuration and start make. It does, however, require a good amount of disk space - almost 7 meg (and subject to change; more if you are not doing the simple compile - more on that later). It also needs a good bit of memory. IV.B. Basic Compilation NetHack can be built with SAS/C version 5.10b, Manx/Aztec version 5, or the registered version of DICE. The "official" compiler for NetHack 3.1 patchlevel 0 is SAS/C 5.10b - we expect to be moving to SAS/C version 6.2 after it is released (6.0 was not available soon enough to gain our confidence for releasing binaries based on it). The game will compile under SAS/C 6.x with small changes. IV.B.1. Introduction to Compiling NetHack Before doing any compilation, read the README files distributed with the source. These should familiarize you with the source tree layout, and what files are shared with what computers. Generally, everything in the sys/amiga directory is used exclusively by the Amiga. The makefile (Makefile.ami) is set up to depend upon certain assignments, providing the developer with a fairly flexible environment. See makefile.ami for assignment assumptions. Edit config.h to your liking and system configuration. The following need to be checked: UNIX - undef MACROCPATH - undef HACKDIR - define as "NetHack:" For SAS/C 6.x, in config.h, make sure that '#define NEARDATA' is used and not '#define NEARDATA __near'. The v5 compiler recognizes a different syntax than the v6 compiler for this construct. You will need to build without __near for now to get around this problem. At this point, you're almost ready to begin a compile. Read VERY CAREFULLY through the Makefile to familiarize yourself with which assignments are assumed. Otherwise, you're going to get something like "Insert NHS: in any drive." requestors. You will need the programs uudecode, flex, and bison. Be sure the p bit is set in the permissions for ifchange. The first thing Makefile.ami does is build a program called 'makedefs', which handles a variety of data file generation, and a pair of programs called 'lev_comp' and 'dgn_comp' which compile the special levels. Makedefs will then be run to create a few files, followed by an alphabetically sorted compilation of the entire source tree. This compilation process will compile selected files from the Amiga:, Share:, and NHS: directories. If all goes well, all of the objects will be linked together to form a binary. After building the main binary, a make install will build the auxiliary files including help files, special levels, icons, and the font files and will put these files into their final positions. The first make run should be done in OBJ: and the make install should be done in NetHack:; for both runs, the makefile is Amiga:Makefile.ami. For SAS/C 6.x: in Makefile.ami, comment out the SAS5 macros and uncomment the SAS6 macros. Note that not all the source is simple C code. If you are modifying lev_comp or dgn_comp you may need bison and/or flex (depending on what modifications you are making). If you wish to modify the Intuition windows in HackWB, the (uuencoded) PowerWindows files are provided. You do not need any of these tools to simply build NetHack - all the C output files are provided in the source distribution. Also, the ifchange script requires a version of diff that produces standard Unix format context diffs for proper operation - the version shipped with SASC is not sufficient. If you do not have bison and flex, copy the files from Share:. The include files go in incl: and the C files go in util:. If the compile fails due to prototype errors for malloc and realloc, try deleting the first line of lev_comp.c and dgn_comp.c. IV.B.2. Compiling NetHack with SAS/C version 5 NOTE WELL - Amiga NetHack will be dropping support for SAS/C version 5 and moving to SAS/C version 6 almost immediately. Upgrade now! You have been warned. This version of NetHack was developed with SAS/C 5.10b and SAS/C 6.1. Earlier versions of the compiler are known to cause problems - don't use them. A couple of notes and warnings from the SAS/C users on the team: * Included in the SAS/C port is code for generating a SnapShot.tb file upon catching various internal disasters. That is why the -d1 flag is in the makefile. This adds about 270K to the disk image, but it does not increase the run time memory requirements. (But note that this is not useful for split binaries - see below.) * The 5.10b optimizer does not produce correct code for NetHack. * There are a large number of warnings under SAS/C, which are harmless. * Some versions of flex produce #line statements with the file name in quotes: version 5.10b doesn't like this. For some reason lc tries to access this file, which results in a bogus requestor for "Util: (yes, there is one quote mark in front of Util:) - select cancel and ignore the problem or add -L to the FLEX definition in Makefile.ami. SAS says that this will be fixed in 6.0. IV.B.3. Compiling NetHack with SAS/C version 6 Very simliar to compiling under version 5 except all the command lines are different - see the Makefile. Also, see the note above about NEARDATA. IV.B.4. Compiling NetHack with Manx/Aztec version 5 The Manx port has not been tested recently and is probably broken. We expect to have it back in shape soon but we welcome context diffs. As of the last check, NetHack required version 5.0B of the compiler. IV.B.5 Compiling NetHack with the registered version of DICE The DICE port was complete at one point but has not been tested in several months - it probably will not work as is. We welcome context diffs (or volunteers) to fix it. IV.C. Advanced Compilation As mentioned above, NetHack is very large. There are several techniques under development by the Amiga NetHack Team for dealing with the situation. As they are completed, they will be documented here. Before attempting any of them, you MUST do a "normal" build as documented above; the techniques described below require the auxiliary files from a normal build to form a complete NetHack installation. IV.C.1 Splitter Splitter addresses two problems with NetHack: first, the long startup time of the game, and second, the size of the binary (which will not fit on a single disk). See the file split/split.doc for information on splitter. The normal install target in Makefile.ami will build the split version of NetHack as part of the normal install process; the front ends will run from either the normal version (HackExe:NetHack) or, preferably, from the split version (NetHack.c#? NetHack.d#?) - the decision is based on the presence (or absence) of HackExe:NetHack.dir. Note that the contents of NetHack.dir after a build will generally not be the correct contents for a floppy based system.