nethack/sys/vms/Install370.vms

               Instructions for Building and Installing NetHack 3.7.0
                     on a VSI openVMS 9.2 system
                    =========================================

This contains a description of how to build NetHack-3.7.0 on VSI OpenVMS 9.2.
This process uses Gnu Make 4.1 (minimum) for VMS to carry out the build.
Last tested with VSI C x86-64 V7.5-009 (GEM 50XBR) on OpenVMS x86_64 V9.2-2.

0.  Please read this entire file before trying to build or install
    NetHack, then read it again!

1.  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
        [.lib.lua546]    -- Lua distribution from https://www.lua.org/
        [.src]           -- primary source files
        [.sys]           -- parent for [.sys.*]
        [.sys.share]     -- files shared by several ports, including 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)

2.  From the top of the NetHack 3.7 distribution, issue the following
    pair of commands to distribute the GNU make Makefile.vms files to their
    working locations for building NetHack:
        $ set def [.sys.vms]
        $ @vmssetup.com
        $ set def [-.-]
    That will place renamed copies of the following files like so,
    relative to the top of the NetHack source tree:
        [.sys.vms]Makefile_top.vms -> Makefile.vms
        [.sys.vms]Makefile_dat.vms -> [.dat]Makefile.vms
        [.sys.vms]Makefile_doc.vms -> [.doc]Makefile.vms
        [.sys.vms]Makefile_src.vms -> [.src]Makefile.vms
        [.sys.vms]Makefile_utl.vms -> [.util]Makefile.vms

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.
    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.  After the above steps, issue the following command from the top of the
    NetHack source tree to build the game from sources:
        make

5.  [ FIXME: this step is not in the Makefile_top.vms yet 2024/03/08 ]
    After compilation, it's time to perform installation. Issue the
    following command from the top of the NetHack source tree:
        make install

6.  To clean files left over from the build, issue the following command
    from the top of the Nethack source tree:
        make clean

7.  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
    [.doc]nethack.txt) are also applicable to VMS.  Some comments at the
    beginning of nethack.com illustrate several of the options.  New
    players should read the file "Guidebook.txt" which will be copied
    into the playground directory as "Guidebook.doc".


Notes:

1.  Save files and bones files from 3.6.x and earlier versions will not
    work with 3.7.0. The scoreboard file (RECORD) from 3.6.x or 3.4.x or
    3.3.x should work.

2.  To specify user-preference options in your environment, define the
    logical name NETHACKOPTIONS to have the value of a quoted string
    containing a comma separated list of option values.  The option names
    are case-insensitive.
       $ define nethackoptions "noAutoPickup,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.  The "menustyle" option controls some
    aspects of the user interface, and can be set to "menustyle:traditional"
    to make nethack behave more like older versions.

    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 similar to
    NETHACKOPTIONS, but multiple lines can be used, each must start with
    OPTIONS=, and comments can be included by placing '#' in the first
    column.  Several options which take more complex values (graphics
    representation) can also be present; see the "Guidebook" for details.
    (Guidebook.txt can be found in the [.doc] subdirectory; a copy gets
    placed in the playground directory by install.com.  Also, an example
    configuration file can be found in [.win.X11]nethack.rc.)

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

4.  Both vmsbuild.com and Makefile.src have provisions to build NetHack's
    There is currently no working version of the 'curses' interface for
    OpenVMS. The NetHack source code for it won't compile using
    the implementation of curses which is supplied with VMS (either the
    VMS-specific variant or the BSD-derived one).  If someone manages
    to port 'ncurses' or 'PDcurses' to OpenVMS, it may be possible to
    use either of those, as ncurses works on Unix and PDcurses works
    on Windows and MS-DOS.

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

6.  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.  (For recent versions of VMS, SET ACL was
    made obsolete in favor of SET FILE/ACL, which in turn has been made
    obsolete in favor of SET SECURITY/CLASS=FILE/ACL; however, the older
    forms will still work.)  '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.

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

8.  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.  A somewhat
    more elaborate log file named XLOGFILE containing more information is
    handled similarly.

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

    [That was written many years ago and the chance of it still working
    is very small.]

10. 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 -D 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.
       $ @hackdir:nethack "-D"
    Any character name you specify will be ignored in favor of "wizard".

    [More out of date information.  Rather than compile-time Local_WIZARD,
    users(s) allowed to run in wizard mode are now controlled by the entry
    WIZARDS in the file SYSCONF.]

11. At program startup time, NetHack uses the empty file PERM to prevent
    two different processes from using the same character name (under the
    same UIC ownership) at the same time.  It does this by temporarily
    giving that file a second directory entry named PERM.LOCK, then
    removing the alternate entry once started.  If the PERM file is
    missing or inaccessible, NetHack will give a message and then quit.
    Several possible messages and their usual causes are:
       Can't find file perm;1 to lock!
    PERM.;1 is missing from the playground directory.  Fix:  reinstall
    the playground directory using install.com, or use CREATE or an editor
    to make an empty file named PERM.  Version number must be 1.
       Can't lock perm;1 due to directory protection.
    The playground directory is not allowing write access.  Fix:  players
    need to be able to write files for dungeon levels and "bones" into
    the playground directory.  Set the protection or ACL on the xxx.DIR;1
    file in the playground's parent directory to allow write access.
       Can't unlink perm.lock;1.
    The empty file PERM.;1 is protected against delete access; only matters
    under some versions of VMS.  Fix:  set the protection or ACL on PERM.;1
    to allow delete access to players.  Under VMS V5.5-2, delete access is
    not necessary.  PERM does not have to remain writable.
       Waiting for access to perm;1.  (# retries left).
    If some other process is also starting up NetHack at about the same
    time, you may have to wait a short period.  NetHack will retry once
    per second, counting down to 0.  If 0 is reached, the message
       Perhaps there is an old perm.lock;1 around?
    will be displayed and then NetHack will give up.  Fix:  to forcibly
    remove a stale PERM.LOCK entry, issue the following command
       $ SET FILE/REMOVE PERM.LOCK;1
    from the playground directory.  The file PERM should remain intact.
    Do not use that command for real files, only alternate directory
    entries.  If output from a DIRECTORY command on the playground reports
       PERM.LOCK;1          no such file
    then someone has deleted PERM.;1 while the synonym entry was still
    in place, and PERM.LOCK was left as a dangling name which no longer
    points at any file.  The SET FILE/REMOVE command above will fix the
    dangling name; a new PERM.;1 will need to be created as mentioned above.

    In similar fashion, synchronized access to the scoreboard file RECORD
    is accomplished using temporary entry RECORD.LOCK and LOGFILE using
    entry LOGFILE.LOCK.

12. If necessary, send problem reports via e-mail to
       <devteam@nethack.org>
    Always include version information for NetHack, the operating system
    version, and the C compiler and version used, and the version of GNU
    make utility used.

8-March-2024
# NetHack 3.7  Install370.vms       $NHDT-Date: 1575245132 2019/12/02 00:05:32 $  $NHDT-Branch: NetHack-3.6 $:$NHDT-Revision: 1.16 $
# NetHack may be freely redistributed.  See license for details.