1 Instructions for installing aNetHack 0.0.1
3 =======================================
4 NB: We are gradually replacing this process with the process documented in
5 the file NewInstall.unx.
7 0. Read this entire file before starting, and come back to the Notes
8 below if you have any problems. If you are trying to use X11,
9 also read all of win/X11/Install.X11, or read win/Qt/Install.Qt
10 if you are using Qt or KDE under X11. For help in controlling
11 and running the game after it is installed, see the '?' command
12 within the game and doc/Guidebook (non-installers want to know
13 about those things too).
15 1. Make sure all the aNetHack files are in the appropriate directory
16 structure. You should have a main directory with subdirectories
17 dat, doc, include, src, util, sys/share, sys/unix, win/tty, win/X11,
18 and win/Qt. You may have other subdirectories under sys and win,
19 but they will not affect compilation for a UNIX system. If you do
20 not follow this structure, the Makefiles will not function properly.
21 The .c files for the main program belong in src, those for utility
22 programs in util, and UNIX-specific ones in sys/unix. All the .h
23 files belong in include, the documentation in doc, and assorted
24 data files in dat. Some UNIX versions may also be interested in
25 sys/share's random.c or its lex/yacc output, as explained in note 11.
26 (A more detailed explanation of the directory structure may be found
27 in Files, which should be in the top directory.)
29 2. Your Makefiles may still be in sys/unix with tags on the end of them.
30 If so, run "sh setup.sh hints/unix" in that directory to
31 distribute the Makefiles to places they can do their work. (If
32 later official patches change these Makefiles, setup.sh should
33 be rerun to make sure you use the current copies.)
35 3. Go to the include subdirectory and edit config.h according to the
36 comments to match your system and desired set of features. Similarly
37 edit unixconf.h. Please see the "Notes:" section, below, for some
38 configuration hints for particular systems.
40 4. If you want to, look through system.h. This file attempts to match the
41 types for system calls and library routines with various flavors of
42 operating systems. Leaving this file alone is unlikely to cause worse
43 problems than lint errors, but it's worth checking if you get compile
44 errors, especially if you have an unusual system.
46 5. Go to the src subdirectory and look at the top of topten.c. You may want
47 to change the definitions of PERSMAX and PERS_IS_UID here to get different
48 behavior from the high score list.
50 6. Edit the top sections of the src and util Makefiles. (If you are doing
51 a full recompile, or if you got your files from someplace besides the
52 official distribution, type 'touch makedefs.c' to make sure certain files
53 (onames.h, pm.h) get remade instead of relying on the potentially
54 troublesome timestamps.) Then type 'make' in src and go get a cup of
55 coffee or take a nap, depending on the speed of your system. You should
56 now have created the game executable.
58 7. Go back to the top directory and edit that Makefile, explaining where
59 you want everything to be installed.
61 Make sure that you follow the comments about setting HACKDIR -- the
62 installation process will wipe out the contents of the directory you
63 point it at, under the assumption that it's debris from an old version
64 of aNetHack. If this is not the case, you'll want to install somewhere
65 else, or comment out the rm under the install target.
67 The Makefile assumes you want to run aNetHack setuid 'games' to cut down
68 on possible tampering; it's fairly straightforward to comment out the
69 appropriate chmod if you don't want that, or to change any of the rest
70 of the procedure. (Note that if you don't want to run aNetHack either
71 setuid or setgid, and people in more than one group will be playing it,
72 you'll need to go back and set FCMASK to 0666 in unixconf.h and let
73 everybody fiddle with the files aNetHack creates.)
75 If the tbl, nroff or col commands are not available on your system,
76 edit the doc/Makefile and change the GUIDECMD as directed.
78 Type 'make all' from the top directory to set up all the auxiliary
79 files the main executable will use. Then become root if necessary and
80 type 'make install'. Everything should now be set.
82 8. Read doc/recover.man or doc/recover.txt to learn how to use the recover
83 program. The recover program can be used in case of a crash to recover
84 a game that was in progress. The recover command is installed in the
87 9. If you specified SYSCF (and SYSCF_FILE) in config.h, create the file
88 defined as SYSCF_FILE and fill in any of the following values if you
89 wish to override the compiled-in defaults:
90 WIZARDS= a space-separated list of usernames who can use -D
91 If the first character is '*' then any user can use -D.
92 SUPPORT= one line, probably starting with a verb, telling how to
93 contact your local support person/group for aNetHack. If there
94 is no local support, do not use this line. Some sample values:
95 call Joan at +1 312 555-1234.
96 email support@example.com
97 visit http://www.example.com/game-support
98 RECOVER= instructions for running recover. If RECOVER is not available,
99 do not use this line. Some sample values:
100 To get your game recovered, contact support.
101 Run /usr/local/bin/nh-recover to recover your game.
104 This is a standard config file, so blank lines and lines starting with
105 pound signs are ignored; while other, standard options (such as catname)
106 can be specified in this file, this is considered a bug and may be changed
111 1. Save files and bones files from previous versions will not work with
112 aNetHack 0.0.1. Don't bother trying to keep them.
114 2. To install an update of this version of aNetHack after changing something,
115 type 'make update' from the main directory. If you created the new
116 version yourself, it should be safe to use 'make update' as long as you
117 did not add, delete, or reorder monsters or objects and you did not change
118 the format of saved level files. If you did any of these things, you
119 should also remove any saved games and bones levels. (Trying to use such
120 files often produces amusing but useless confusions on the game's part.)
122 3. If you insisted on doing the final installation by hand, you probably
123 forgot to make a save directory. If you don't go back and do this, you
124 won't be able to save games.
126 4. If you get unexplained deaths by trickery, you are probably running
127 aNetHack on a bunch of workstations, but you have overlooked the NETWORK
128 definition in unixconf.h that is necessary in that configuration.
130 5. If spurious characters appear on the screen while throwing, kicking,
131 zapping, etc., it is likely that you have linked the source to the wrong
132 library or mistakenly defined/undefined TERMINFO. A number of systems,
133 such as Xenix, support both the termcap and terminfo terminal capability
134 libraries. In such cases, the TERMINFO definition in unixconf.h and the
135 WINTTYLIB definition in the source Makefile must correspond.
137 If your terminal library does not provide suitable delays, aNetHack will
138 try to fake its own if you set the nonull option.
140 6. Since aNetHack overflows the stock C preprocessors for AT&T 3b1 and 3b2
141 systems ("too many defines"), we are including an alternate preprocessor
142 to allow these folks to compile. This is the DECUS cpp by Martin Minow,
143 slightly modified by Kevin Darcy to use larger buffers, be less verbose,
144 and handle strange constructs in AT&T's include files.
146 To use this preprocessor, unpack the cpp* files found in sys/unix into
147 some handy directory (util will do). For the AT&T machines mentioned
148 above, nothing needs to be configured; you should get a working cpp by
149 merely typing "make -f makefile.txt". To get your compiler to use the
150 new cpp, you will have to add to CFLAGS in src/Makefile and util/Makefile.
151 If you put the cpp files in /foo/bar/util, add "-B/foo/bar/util/ -tp"
152 for a 3b1 or "-Yp,/foo/bar/util" for a 3b2.
154 For any other machine whose preprocessor can't handle the aNetHack source,
155 you'll have to play it by ear. The preprocessor has many esoteric
156 configuration options, but most probably you will only need to change
157 the flags in makefile.txt, and then refer to your compiler's documentation
158 to find the appropriate CFLAGS for the aNetHack Makefiles. (The SunOS flag,
159 for instance, would be "-Qpath /foo/bar/util", although the native cpp
160 has no trouble with aNetHack. So much for standardization.)
162 7. If you are trying to compile aNetHack on an AT&T 3B that is running an
163 OS earlier than SVR3, you are likely to have problems with overflowing
164 symbol tables. This can be worked around by editing the source Makefile
165 to make the Sys.3B2 target work more like the SysV-AT target, adding
166 -DDUMB to CFLAGS and DUMB.Setup to the Sys.3B2 dependency line. The
167 compiler provided with later versions of the OS has a large enough
168 symbol table that it does not need this workaround.
170 8. If aNetHack seems to compile fine, starts up, allows you to pick a
171 character, and then hangs indefinitely, gets a segmentation fault, or
172 traps you in a single room on the first level, you might try changing
173 the schar and uchar definitions in config.h to short ints. This problem
174 is known to occur on the AT&T 3B series, Silicon Graphics Irises, and
175 IBM systems (PC/RT & RS/6000) running AIX, and may occur on other
178 This problem is really most likely caused by having a non-__STDC__
179 compiler with char's unsigned by default. Since some such compilers
180 don't understand the new "signed" keyword, and others don't have signed
181 characters to use (the 3B2 line falls into this category), "signed"
182 is #ifdefed away for them. If you are sure your compiler can deal
183 with it, you can add your compiler to the __HC__ case in tradstdc.h.
185 Alternatively, if the compiler supports a command line switch for
186 setting the default char type to signed, you could try setting it in
187 the Makefiles. The appropriate switch for SGI Irises with MIPS C
188 compiler is "-signed" and for RS/6000's with standard cc "-qchars=signed".
189 (SGI machines running IRIX 4.0.x have a compiler close enough to
190 standard to suit aNetHack, so you may merely use the suggested flags
193 Note that at least RS/6000's seem to like changing the default to
194 signed better but there is also a problem: The lexers created by
195 the standard lex program in AIX may come out faulty when this switch
196 is used (known to happen at least in AIX 3.1.3), so you may have to
197 use an alternative, like flex, which is available at major archive
198 sites (see notes 10 and 11).
200 By AIX 3.2.5, this whole problem should be taken care of automatically
201 (but AIX_31 should still be defined in unixconf.h for other reasons).
203 9. Under SCO UNIX, you may have all sorts of complaints about
204 include/obj.h. Go to the file and uncomment the marked line, working
205 around the fact that SCO's system include files preempt a major
206 aNetHack structure name. Also, there are difficulties with SCO's cc
207 that thus far have been solved only by changing compilers; one report
208 says gcc-aNetHack works, and another says rcc-aNetHack can be made to
209 work by defining NOTSTDC, applying note 8, and compiling with -tinfo
210 and -xenix. The cc problems are old enough that a new, working
211 version may have been released by this time.
213 10. Xenix/286's lex generates a faulty lexical analyser from lev_comp.l.
214 The beta-release of flex 2.3 (available from uunet, osu-cis,
215 prep.ai.mit.edu, etc.) can be used to generate the lexer.
216 The only change to flex is to change "#define yyleng (yy_cp - yy_bp)"
217 to "#define yyleng (int)(yy_cp - yy_bp)" in flex.skel.
218 Flex is not needed with Xenix/386, as its lex generates a proper lexical
219 analyser. [Xenix instructions by J.T. Conklin]
221 11. If your system does not have a lex/yacc or flex/bison combination
222 capable of producing the dungeon and level compilers, lex and yacc
223 output from one of our development systems can be found in sys/share.
224 Unfortunately, this output is less portable than the rest of the code,
225 as it contains skeleton parsing code provided by the specific vendor
226 who has no particular incentive to make such skeletons portable, but
227 the output works on most systems. To try it on yours, copy dgn_comp.h
228 and lev_comp.h to include and dgn_lex.c, dgn_yacc.c, lev_lex.c, and
231 12. Yes, Virginia, you compile aNetHack for a NeXT as if it ran UNIX instead
232 of Mach. Just tell aNetHack you're a BSD system (Mach is extremely
233 close to BSD UNIX for traditional system calls, so this is also a
234 likely thing to try for any other programs you want to compile).
236 If you get errors when starting anethack warning that "Setuid execution is
237 not allowed", you might want to re-install using the setgid option instead
238 (see Note 7 above, and the setgid comment in the toplevel Makefile).
240 13. If you are using Solaris 2.x (aka SunOS 5.x) you shouldn't have to
241 do any system configuration -- this is the default. In case it is
242 messed up, follow these instructions.
244 Solaris is basically a SVR4 system, not a BSD system. Therefore, you
245 configure config.h and unixconf.h as per a SVR4 system:
247 config.h: UNIX, TTY_GRAPHICS
248 unixconf.h: SYSV, SVR4, TERMINFO, POSIX_JOB_CONTROL, POSIX_TYPES
250 X11_GRAPHICS does work. Do not define OPENWINBUG. You may safely define
251 NETWORK, TEXTCOLOR if desired. Other #defines in these files may be
252 defined too, as needed. Just make sure that the set mentioned here are
253 not misdefined, or your compile will fail (do _not_ define BSD or SUNOS4).
254 Unless you are using gzip you will probably want to define COMPRESS to
255 be "/usr/bin/compress".
257 When compiling, make sure that you use the ANSI C SVR4 compatible
258 compiler, /usr/bin/cc, or gcc, but _not_ ucbcc. The lattermost will
259 not work. After this, you should get a clean compile.
261 Also, it is recommended that you use FLEX instead of the standard
262 lex bundled with Solaris 2.x (even if that last one should work ;-).
264 14. If your machine is a 286, 386, or 486 running an appropriate OS, you
265 may wish to use the console speaker driver included in
266 sys/unix/snd86unx.shr. This will allow audible music to be played
267 on your console speaker in certain appropriate game situations. The only
268 modification to the main-line code needed to enable use of the driver
269 is defining UNIX386MUSIC or VPIX_MUSIC in unixconf.h.
271 15. If you are trying to cross-compile for another system, there is some
272 support in the src and util Makefiles, but there are still other
273 complications. It may well be best to make another copy of util,
274 util2, to compile target copies of makedefs, lev_comp, and recover
275 (duplicating the cross-compilation settings from the src Makefile)
276 without disturbing the main build.
278 You can use the host makedefs for everything but "makedefs -v", which
279 creates include/date.h, which provides various sanity-checking values
280 for making sure files read by aNetHack at run-time are compatible.
281 These values depend on the endianness of your processor, its type
282 sizes, and its compiler's idea of struct packing. Your host and target
283 computers may disagree on these things, so you'll need to build a target
284 version of makedefs, run "makedefs -v" on your target, and bring the
285 resulting date.h back for the builds on the host. (Making sure the host
286 makedefs doesn't decide it needs to overwrite it for you. :-)
288 You also need a target version of lev_comp, and to provide it with all
289 the dat/*.des files, and copy all the resulting *.lev files back for
290 packaging on the host.
292 For recover, you just want the target binary to install on the target.