InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / nethack-3.1 / sys / vms / Install.vms < prev next >

Wrap

Text File | 1993-01-25 | 28.7 KB | 484 lines

Instructions for Installing NetHack 3.1.0 on a VMS system ========================================= 0. Please read this entire file before trying to build or install NetHack, then read it again! 1. Building NetHack requires a C compiler (either VAX C, DEC C, or GNU C) and VMS version V4.6 or later (but see note #11). This release has been tested on VAX/VMS V5.5-2, T6.0, and Alpha/VMS V1.0. The build procedure (vmsbuild.com) should not need to be modified; it accepts an option for selecting VAXC vs GNUC, and it can detect different versions of VAXC to use appropriate CC command qualifiers. Versions of VAXC earlier than V2.3 will produce many warning messages (about 150 per source file; over to 18,000 total!), but NetHack has been verified to compile, link, and execute correctly when built with VAXC V2.2 using vmsbuild.com. There is also a set of Makefiles suitable for use with MMS; they may or may not work with other make utilities. 2. Make sure all the NetHack files are in the appropriate directory structure. You should set up a directory--referred to as "top" below and in some of the assorted files, but which may be a subdirectory-- that has these subdirectories [.dat] -- data files [.doc] -- documentation files [.include] -- C header files [.src] -- primary source files [.sys] -- parent for [.sys.*] [.sys .share] -- files shared by several ports, incl. VMS [.sys .vms] -- VMS-specific source and support files [.util] -- sources for essential utility programs [.win] -- parent for [.win.*] [.win .tty] -- "window" routines for ordinary terminals (including terminal windows on workstations) The following subdirectories may be present, but are not useful for building NetHack on VMS and are not required: [.sys .amiga] -- AmigaDOS [.sys .amiga .splitter] [.sys .atari] -- Atari TOS [.sys .mac] -- Macintosh [.sys .msdos] -- MSDOS for IBM PCs and compatibles [.sys .os2] -- OS/2 [.sys .unix] -- guess :-) [.win .X11] -- window routines for X-Windows; requires X11R4 or later and MIT's Athena Widget set You must arrange things in this structure or the supplied procedures and instructions in this file will not work properly. Several DCL command files are present in the [.sys.vms] subdirectory and won't work as intended if they're moved elsewhere. The file called Files in the top directory contains lists of everything that should be in each subdirectory, including things that are constructed as NetHack is being built. If you obtain the NetHack distribution via the "shar" packaging used for Usenet newsgroup comp.sources.games and its archives, you may have to reconstruct several files that were split for posting. At the time of this writing, the list of files needing such treatment is not known, so they can't be enumerated here or handled automatically be the build procedures. 3. Prior to beginning compilation, go to the [.include] subdirectory and edit vmsconf.h according to its comments. You should set Local_WIZARD and Local_HACKDIR to appropriate values, and you might want to define TEXTCOLOR if you have any color VAXstations or color terminals which handle ANSI-format escape sequences to set foreground and background color for text characters. (VT241/VT340 color graphics won't work.) Other things which may be of interest are SECURE if you intend to set up NetHack as an installed image which is granted privileges, and SHELL which should be disabled if you intend to allow captive accounts to run NetHack. You may also want to edit file config.h, but that's only necessary if you want or need to disable some of the game options. The distributed copy of config.h will work successfully on VMS; vmsconf.h has conditional code to deal with the UNIX-specific items. 4. If you have the programming utilities lex or flex and yacc or bison, you may edit the procedure [.sys.vms]spec_lev.com and execute it to process several source files for NetHack's special level and dungeon compilers. If you don't modify spec_lev.com, it will copy some pre-processed versions of the appropriate files (dgn_lex.c, lev_lex.c, dgn_yacc.c, lev_yacc.c, dgn_comp.h, and lev_comp.h) from [.sys.share] into [.util]*.c and [.include]*.h. $ @[.SYS.VMS]SPEC_LEV ![OPTIONAL] If you perform this step, do it prior to executing vmsbuild.com; if you don't perform this step, vmsbuild.com will do so for you. 5. If you are using DEC C (not to be confused with Digital's VAX C) as your compiler, you should create an empty file called CRTL.OPT in the [.src] subdirectory. This is a linker options file for accessing the C run-time library. If you don't create it, vmsbuild.com will construct one suitable for linking with shareable VAXCRTL. Programs compiled with DEC C should link with DECC$SHR instead; no special linker options are needed in that case and VAXCRTL should be avoided. You should also create a DCL symbol for invoking CC that specifies VAXC compatibility mode. $ CC == "CC/Standard=VAXC" You might also want to specify /noOptimize if you don't trust the V1 compiler's optimizer yet. No other special qualifiers are needed. 6. To build NETHACK.EXE and its auxiliary programs, execute the following DCL command: $ @[.SYS.VMS]VMSBUILD !defaults to VAXC unless symbol 'CC' exists or $ @[.SYS.VMS]VMSBUILD "GNUC" It can take quite a bit of time for a full build to complete. vmsbuild.com will display some feedback as it executes; generally this will be the name of each source file that's about to be compiled or the name of the executable that has just been linked. 7. After compilation, it's time to perform installation. Go back to the top directory. Either edit [.sys.vms]install.com to indicate where you want everything to be installed, or specify the location and "playground" owner on the command line. Then execute either $ @[.SYS.VMS]INSTALL or $ @[.SYS.VMS]INSTALL location owner where location is a device:[directory] specification and owner is either a rights identifier or UIC. If install.com is not modified and if values aren't supplied on the command line, the default values used are the translation of logical name HACKDIR, if any, or else [.PLAY] (relative to the current directory), and the UIC for the current process. install.com will use the auxiliary programs constructed by vmsbuild.com to process quite a few data files in the [.dat] subdirectory. Then it will create the playground directory, if necessary, plus the associated [.save] subdirectory. Next it will copy the data files into the playground; this step can take a while. Finally it will copy nethack.exe and a few additional support files. After it completes, the files [.src]nethack.olb, [.src]nethack.exe, [.util]*.obj, [.util]*_comp.exe, and [.util]makedefs.exe can be deleted in order to save disk space if desired. The other program, [.util]recover.exe, should not be deleted unless you make a copy of it somewhere--perhaps in the playground directory--first. It can be used to resurrect some games disrupted by system or program crash. 8. The file nethack.com which is copied to the playground directory can be used to invoke NetHack, or nethack.exe can be run directly. Most of the command-line options specified in the Unix man-page (file [.dat]nethack.6) are also applicable to VMS. Some comments at the beginning of nethack.com illustrate several of the options. New players should read the document file "Guidebook.txt" which will be available in the playground directory. Notes: 1. Save files and bones files from previous versions will not work with NetHack 3.1.0. Don't bother trying to keep them. Ditto for RECORD, the scoreboard file. One minor change of note is that the default name for a player's character is now a lowercase copy of the username. 2. To specify user-preference options in your environment, define the logical name NETHACKOPTIONS to have value of a quoted string containing a comma separated list of option values. The option names are case-insensitive. $ define nethackoptions "noPickup,Dog:Rover,Cat:Felix,DECgraphics" One value you'll probably want to specify is "noLegacy" to turn off the initial introductory passage. The "checkpoint" option controls whether or not enough data is saved to disk so that the set of level files left behind after a crash contains sufficient information for recover.exe to be able to construct a save file after the fact. The tradeoff for enabling checkpoint is that using it makes level changes do more I/O and take longer. If logical name or DCL symbol NETHACKOPTIONS is not defined, NetHack will try HACKOPTIONS instead. Regardless of whether or not either is defined, it will also try to find a configuration file containing additional option settings. If the value of the translation of NETHACKOPTIONS--or HACKOPTIONS--begins with an "@" character then the rest of the translation is assumed to be the name of the configuration file. Otherwise, the following are tried: file specified by logical name NETHACKINI, file SYS$LOGIN:NETHACK.INI, and file HOME:NETHACK.CNF (note that the C run-time library sets up the value of HOME to match sys$login). Syntax for the configuration file is essentially the same as for NETHACKOPTIONS, but multiple lines can be used and comments can be included by placing '#' in the first column. 3. Instead of using vmsbuild.com to compile and link everything, you can use the set of Makefiles found in the vms subdirectory, provided you have an appropriate and compatible make utility. They've been tested using Digital's MMS. There are five of them, and the suffix or filetype on their names indicates where they should be placed. $ copy [.sys.vms]Makefile.top []Makefile. $ copy [.sys.vms]Makefile.src [.src]Makefile. $ copy [.sys.vms]Makefile.utl [.util]Makefile. $ copy [.sys.vms]Makefile.dat [.dat]Makefile. $ copy [.sys.vms]Makefile.doc [.doc]Makefile. After doing that, edit [.src]Makefile and [.util]Makefile to specify pertinent compiler options in CFLAGS, linker options in LFLAGS, and libraries in LIBS and/or MORELIBS if the default values aren't right. Be sure to make compatible compilation and linking settings in both files. While in there, edit [.util]Makefile to specify the appropriate values for lex and yacc, _or_ move to that directory and use MMS or make to build targets no_lex and no_yacc which will copy several pre-processed files from [.sys.share] into [.util]. Finally, edit Makefile in the top directory to specify values for GAMEDIR and GAMEOWNER. This top Makefile invokes [.sys.vms]install.com to do much of the actual installation work, so if you want to make any customizations or file protection changes, edit install.com to suit. Also set MAKE in all of the Makefiles to the appropriate command if not using MMS. Once the Makefiles are tailored for your site, give the command $ mms all,install or $ make all install To compile and install everything. The object files compiled via the Makefiles are left as individual .OBJ files rather than placed into an object library (in contrast to step #7 above and note #12 below). These Makefiles are provided on an as-is basis; vmsbuild.com is the preferred way to compile because it's guaranteed to compile and link everything. 4. VMS NetHack uses the termcap routines borrowed from GNU Emacs. These have been supplied for those who do not already have GNU Emacs, but they are not properly a part of the NetHack distribution. Since these files (gnutermcap.c and gnutparam.c) bear the usual GNU license, any executable made with these files is also under the GNU license, which among other things means you must be prepared to distribute all the source that went into the executable if you distribute the executable. See the GNU license in the files for further details. Since NetHack itself has a very similar license, this should not be an issue. 5. termcap is an ASCII data file containing descriptions of terminal capabilities and the escape sequences that software must use to take advantage of them. If you do not already have a termcap file in use on your system there is a small one in file [.SYS.SHARE]TERMCAP. It contains definitions for common Digital terminals, also suitable for most clones and emulators. This file is copied into the playground by install.com, and NetHack will use it if it can't find any other one. NetHack uses the following sequence to attempt to locate the termcap file: translation of the logical name TERMCAP (used as-is), file NETHACKDIR:TERMCAP, similar file HACKDIR:TERMCAP, GNU-Emacs file EMACS_LIBRARY:[ETC]TERMCAP.DAT, file []TERMCAP, and lastly file $TERMCAP (which most likely would be a logical name). If NetHack can't find the termcap file, or if the above search sequence finds a different one than you'd prefer, then use the DCL ASSIGN or DEFINE command to define a value for logical name TERMCAP. NetHack also tries fairly hard to figure out what kind of terminal you're using. It checks for logical names (or symbols) NETHACK_TERM, HACK_TERM, EMACS_TERM, and lastly TERM. The last is set up by the C run-time library and you cannot use a logical name or symbol for it. If all those fail, or if whichever one succeeds has a value of "undefined" or "unknown" (which can happen under VMS V5.4-* and V5.5-* for VT420 terminals), NetHack will query the VMS TERMTABLE database used by the SMG library routines. Whatever value NetHack eventually comes up with needs to be the name of an entry in the termcap file, otherwise a message about "Unknown terminal type" will be printed and NetHack will exit. 6. If you want to use GEM C for cross-compiling from VAX/VMS to Alpha/VMS or vice versa, you'll have to build in stages. For the first pass, use a value of CC appropriate for the host system, interactively start vmsbuild.com as described in step #6 above, wait until it has compiled and linked "makedefs", then use <ctrl/C> to interrupt it (after the "12:34 makedefs" feedback message) so that it doesn't waste any time compiling the rest of the code. Consider that to be stage 1. For stage 2, go back to step #5, but set the symbol for invoking CC to have a value similar to the following $ CC == " GEMC/Standard=VAXC" Note the leading space in the value; if that's not included, vmsbuild will take the leading "G" as an indication that GCC is being used and end up selecting some wrong options. Also set up symbols for cross- architecture access to the linker and librarian (these examples assume building an AXP version from a VAX) $ LINK == "LINK/Alpha" !or LINK/VAX $ LIBR == "LIBR/Alpha" !or LIBR/VAX Now re-do step #6, but specify "/noExe" as the 4th parameter to vmsbuild.com. $ @[.SYS.VMS]VMSBUILD "" "" "" "/noExe" Note the three empty strings used as placeholders. That's the end of stage 2; everything will be compiled to object files but no executable files will have been linked. If you don't do things this way, a new version of makedefs will be linked; but since it will be appropriate for the target, vmsbuild's attempt to use it on the host will fail. For stage 3, link nethack.exe using vmsbuild.com $ @[.SYS.VMS]VMSBUILD "LINK" Don't specify "/noExe" this time around or you'll just be wasting your time and CPU cycles. ;-) For stage 4, link all four of the utility programs manually (there's no vmsbuild option for this). Go to the [.util] subdirectory and issue these commands $ LINK makedefs,[-.src]nethack/Lib $ LINK/Exe=[]lev_comp lev_main,lev_yacc,lev_lex,panic,[-.src]nethack/Lib $ LINK/Exe=[]dgn_comp dgn_main,dgn_yacc,dgn_lex,panic,[-.src]nethack/Lib $ LINK recover,[-.src]nethack/Lib Note that these commands are slightly simpler than the corresponding ones used in vmsbuild.com; crtl.opt is expected to be empty (step #5 above) so omitted here, and the identification directive is optional. The installation of the playground (step #7 above) must be done on the target system but should need no special cross-architecture contortions. 7. NetHack contains code which attempts to make it secure in case it's installed with privileges (to allow the playground to be protected against world write access). This has only undergone limited testing, so install NetHack with privileges at your own risk. If you discover any potential security holes, please let us know so that we can take steps to correct the problem(s). NetHack always includes filename punctuation when accessing files, so that it should never be affected by inadvertent or malicious logical name definitions, and it always deactivates installed privileges prior to spawning a subprocess. Note to end users: "installing with privileges" is an option for system managers who set up system-wide access to the game. Since CMKRNL privilege and modification of the system boot routines are both required, it is not an option for ordinary users. There are no explicit instructions on how to do such an installation, because only system managers who are already familiar with the process and its potential security ramifications should even consider it. The default setup by install.com assumes no privileges and uses world-writeable files to allow arbitrary users to play. This is NOT secure and not advisable in any environment where there are untrustworthy users, but works fine for many sites. If you allow users to run NetHack from captive accounts (VMS 5.1-* or earlier) or from restricted accounts (5.2 and later), you should either make sure that they do not have TMPMBX privilege or else disable NetHack's ability to spawn an interactive subprocess. To disable subprocesses, disable the "!" (shell escape) command by commenting out the definition of SHELL in vmsconf.h prior to building the program. This necessity may be removed in some future release, where NetHack will check for captive accounts instead of spawning unconditionally. Note that disabling the SHELL command also prevents spawning MAIL when scrolls of new mail are received. In order for installed privileges to be used at all, the value of HACKDIR (via Local_HACKDIR in vmsconf.h) compiled into the program must correspond to the actual playground directory. If logical name HACKDIR (or NETHACKDIR) is used to override that value, installed privileges will be deactivated unless its value corresponds to the same device and directory as the internal value. If that internal value contains a logical name, only an executive-mode translation will be honored; if there is no such translation, installed privs will be deactivated. To be able to install nethack.exe with privileges (SYSPRV or GRPPRV, perhaps EXQUOTA, depending on site usage and needs), you'll need to link it with debugging and tracebacks both disabled. You can do this by specifying an argument to vmsbuild.com when performing step #6 above; pass it "/noTrace/noDebug" as the 4th parameter. $ @[.SYS.VMS]VMSBUILD "" "" "" "/noTrace/noDebug" /Trace/noDebug is the linker's normal default. If you've already built NetHack, you can relink with tracebacks disabled by doing $ @[.SYS.VMS]VMSBUILD "LINK" "" "" "/noTrace/noDebug" 8. If you can't or won't install nethack.exe with privileges and if you don't have access to a privileged account yourself, then if you intend to allow other users to access your copy of NetHack you should probably place an ACL on the playground directory and its save subdirectory. The access control list should contain a default protection ACE which grants delete+control access to the playground owner (ie, your own account if there's no special games account involved). install.com does not attempt to do this automatically at the present time. After executing install.com to create the playground directory, perform a pair of commands similar to the following $ SET ACL/ACL=(IDENT=your_id, OPTIONS=DEFAULT, ACCESS=R+W+E+D+C) - $_ device:[playground's.parent.directory]playground.DIR $ SET ACL/ACL=(IDENT=your_id, OPTIONS=DEFAULT, ACCESS=R+W+E+D+C) - $_ device:[playground.directory]SAVE.DIR The two commands use the same options, but SET ACL won't accept a list of files to modify. 'your_id' should be the rights identifier which corresponds to the account which should retain access to those files; 'device:[playground's.parent.directory]' is the name of the parent directory for the playground (ie, if your playground directory is disk$foo:[me.games.nethack.play], then you want to specify disk$foo:[me.games.nethack]play.dir on the SET ACL command), and 'device:[playground.directory]' is the playground itself. Those ACLs establish a default protection scheme such that every newly created file in those directories will have an ACL attached to it, and the attached ACL will grant 'your_id' full access to the corresponding file. That should allow you to clear away level files from aborted games, and to delete old save files if necessary. It will not enable you to run recover.exe on behalf of other users, because you won't be able to create files owned by them unless you have elevated privileges. 9. Many NetHack commands can be aborted by sending it the <escape> character when it wants input. This is displayed as ESC inside the game. Digital VK201 keyboards (used by VT2xx and VT3xx and older VAXstations) and VK401 keyboards (used by VT4xx, newer VAXstations, and DEC's X Terminals) do not have an <escape> key. They may transmit <escape> for the <F11> key if the terminal or emulator window is set to operate in VT100 mode, or there may be a setup-type option for making the <` | ~> key behave as <escape>. If your terminal does not have that, or if it's set to a mode where that won't work, then just use <ctrl/[> instead. (Press the "[" key while holding down the "Ctrl" key, then release both; <escape> and <ctrl/[> have the same ASCII code and are indistinguishable once they reach the computer; note that VAXstations and X Terminals _can_ tell the difference, but that won't matter for NetHack.) VMS NetHack is configured to use the SYS$QIOW system service for reading characters from the keyboard. This allows ^C and ^Y (as well as ^X and ^O for wizard mode debugging) to be used as commands without being intercepted or interpreted by the terminal driver. The code which parses arrow and function keys is not perfect, and it's possible to get strange results if you hold such keys down to just type too quickly, particularly on slow multiplexor lines. Those keys are never needed in actual play, and most function keys are just treated as <escape> for use in aborting partial commands. VMS NetHack also still has code to use SMG$READ_KEYSTROKE instead. That can be activated by modifying vmsconf.h and recompiling, but it should never be necessary. If you use it, you'll need to press either <esc> or <ctrl/[> twice to abort partial commands, or else press an arbitrary function key, such as <PF4>, once. If SUSPEND is defined in vmsconf.h, <ctrl/Z> is used for that command. Since Unix-style job control is not available, it's used for connecting to the parent process if NetHack is running in a subprocess. When not in a subprocess, it doesn't do anything except give a message to the effect that it's not doing anything.... The suspend command does not save the current game; if you use ^Z to attach to your parent process, be sure to remember to eventually reattach to the NetHack subprocess; otherwise the game in progress won't get saved when you logout. 10. NetHack optionally maintains a logfile which receives one line appended to it whenever a game ends. This can be disabled entirely by adding an "#undef LOGFILE" directive to vmsconf.h prior to building the program, or it can be disabled later by removing the file(s) LOGFILE.;* from the playground directory. If not disabled prior to compilation, the logfile can be reinitialized by simply creating an empty file named LOGFILE in the playground, but make sure that users are able to write into it, or new entries will not be appended. 11. Some attempt at support for VMS versions earlier than V4.6 has been included, but no such obsolete system was available for testing it. vmsbuild.com detects the need for the extra support routines and arranges automatically for them to be compiled. The reason that special support is needed is that the C Run-Time Library (VAXCRTL) underwent a major revision for VMS V4.6 and several routines which NetHack utilizes were not available prior to that upgrade. 12. vmsbuild.com collects almost all of the object files (xxx.OBJ) into an object library (NETHACK.OLB) as it compiles the source files. This should prevent the quota-exceeded problems from the linker that some sites have reported for prior versions. Note that if you compile any source files manually, you'll need to replace those modules in the object library prior to linking the program: $ cc/include=[-.include] [-.sys.vms]vmstty !for example $ libr/obj []nethack vmstty !replace VMSTTY $ @[-.sys.vms]vmsbuild LINK !re-link NETHACK.EXE If you forget to replace the library entry, your newly compiled code will not be included in the new executable image. 13. To access "wizard mode"--intended for debugging purposes, not to spoil the game with unlimited wishes--you must be running from the username compiled into the game via Local_WIZARD in vmsconf.h, and you must specify "-D" on the command line when invoking NetHack. Note that it must be uppercase, and it must be in quotes to prevent the C run-time library's program startup code from converting it into lowercase. Any character name will be ignored in favor of "wizard". 14. Unless you have both Motif and the Athena Widget set from MIT, you will not be able to use the X11 interface on VMS. Even if you do have both those things, such a configuration has not been tested and there are no provisions for it in vmsbuild.com. Makefile.src does have the extra source files listed, but not the necessary libraries. The X11 port will not compile and link with DECwindows, but it will be able to display on a VMS DECwindows X server provided that it and its Unix X client have a compatible transport between them (either TCP/IP added to VMS or DECnet added to Unix) and session security is set up appropriately. You'll need to add the contents of file [.win.X11]NetHack.ad into your DECW$USER_DEFAULTS:DECW$XDEFAULTS.DAT, and modify some of the lines. The DECwindows window manager does not support having input focus automatically follow the pointer, so you should uncomment the "NetHack*autofocus" resource line. (For Motif this may not be necessary, depending on customization options.) Uncommenting the "NetHack*slow" line is highly recommended. You'll also need to set "NetHack*fonts: fixed" (rather than "variable"), and either set the map font to "fixed" too or install the "nh10" font that comes in file [.win.X11]nh10.bdf. If NetHack warns that the map font is variable, then something isn't set up properly. After creating or modifying decw$xdefaults.dat, you must restart the window manager in order for any changes to take effect; it's easiest to just make the session manager quit and then log in again. 15. There is no support for VMS POSIX in this release of NetHack. 16. If necessary, send problem reports via e-mail to "nethack-bugs@linc.cis.upenn.edu" (numeric address 130.91.6.8). Always include version information for NetHack, the operating system, and the C compiler used. 23-JAN-1993