Porting

   1   NetHack Porting Guidelines            v 3.6                   1999-11-29
   2
   3
   4      1.0        Introduction
   5
   6         This document goes through the steps required to port NetHack to a
   7 new machine.  The basic steps in porting the program are:
   8
   9         1.  Get the code onto your machine.  The parts of the current
  10             directory setup you definitely need include src (NetHack code
  11             shared by all systems), include (include files), util (code
  12             for utility programs), and dat (various data files).  The
  13             documentation in doc is strongly recommended.  You already
  14             have the files in the top directory since you're reading this
  15             one. :-)
  16
  17             A full list of the distribution files and their associated
  18             OSes may be found in the top-level file "Files".
  19
  20             If your machine uses an OS already supported, you need the sys
  21             subdirectory for that OS and possibly sys/share.  Otherwise,
  22             get the closest match (say sys/msdos for single-tasking OSes
  23             and sys/unix for multi-user OSes, along with sys/share, if
  24             nothing else comes to mind).  You may want others for
  25             comparison.
  26
  27             If your machine uses a windowing system already supported,
  28             you need the win subdirectory for that system (or the
  29             appropriate sys subdirectory if the windowing system was
  30             previously considered restricted to one OS) and possibly
  31             win/share.
  32
  33         2.  Modify the appropriate include files to customize NetHack to
  34             your system.  You may need to add a new OS-specific "*conf.h"
  35             file (see unixconf.h, pcconf.h, tosconf.h, etc. as examples).
  36
  37         3.  If your machine uses a new OS instead of a variant of existing
  38             OSes, add a new sys subdirectory.  Add, if required, a OS-
  39             specific copy of "main.c", "tty.c" and "unix.c".  Possibly
  40             add an OS-specific library (see "msdos.c" and "tos.c" as
  41             examples) to provide functions NetHack wants and your OS lacks.
  42
  43         4.  If your machine uses a new windowing system, follow doc/window.doc
  44             carefully.  Put files implementing these routines in a win or
  45             sys subdirectory as appropriate.
  46
  47         5.  If your compilation environment isn't close to one already
  48             supported, try starting from the UNIX makefiles.  Modify the
  49             top level makefile and the src makefile as required.  Then run
  50             an initial compile.  You are bound to get some errors.  You
  51             should be able to fix them in a fairly simple fashion.  If
  52             things seem to be getting too complex, take a step back, and
  53             possibly send us some mail.  We might be able to help.
  54
  55         6.  Mail all of your fixes to us in a contextual form so that we can
  56             easily integrate them into the code.
  57
  58         One general rule of thumb exists.  Always add code.  Don't delete
  59 somebody else's code for yours -- it won't work on their machine if you do.
  60 Always add your OS specific code inside #ifdef / #else / #endif constructs
  61 so that it will be able to be folded back into the original code easily.
  62
  63
  64      2.0        Include Files
  65
  66      2.1        config.h
  67
  68         The file "config.h" is a master configuration file that determines
  69 the basic features of the game, as well as many of the security options.
  70 It is intended that end users configure the game by editing "config.h" and
  71 an appropriate "*conf.h" file, so any #defines for individual preferences
  72 should be added to those files.  OS-specific #defines that are not intended
  73 to be changed should also go in "*conf.h"; try to find the most appropriate
  74 place for other #defines.
  75
  76         The following sections may require modification:
  77
  78      -  Section 1:      OS and window system selection.
  79                         You may have to put a #define for your OS here.
  80                         If your OS is yet another UNIX variant, put the
  81                         #define in unixconf.h instead.
  82                         An unfortunately large amount of stuff shares
  83                         this section because the #definitions have to
  84                         be seen before *conf.h is reached.  Don't add
  85                         to this unless necessary.
  86
  87      -  Section 2:      Global parameters and filenames.
  88                         These will have to be customized to your system.
  89
  90      -  Section 3:      Type definitions and other compiler behavior.
  91                         These will have to be matched to your compiler.
  92
  93      2.2        global.h
  94
  95         This file defines things specific to NetHack that should not
  96 require modification by an end user.  For a new port, you may have to add
  97 automatic inclusion of another auxiliary config file (*conf.h) which you
  98 wrote for your system.
  99
 100      2.3        extern.h
 101
 102         If you create any new source modules or new functions in old modules,
 103 you must enter the names of the new external references (the functions defined
 104 there for external use) in this file.
 105
 106      2.4        system.h
 107
 108         This file contains references for all hooks into the OS (via the
 109 standard "C" libraries).  Depending on what your standard library looks like,
 110 you may have to put new entries into this file.
 111
 112
 113      3.0        Source files
 114
 115         The first step in getting the game up is to get the "makedefs"
 116 program running.  This program is used to create configuration-specific
 117 files for the game.
 118
 119         Once "makedefs" has been built, the rest of the game can be compiled.
 120 You may have to create an OS-specific module to handle things you want to
 121 use, like a mouse or a ram-disk.
 122
 123         The utility compilers "dgn_comp" and "lev_comp" may be a better
 124 place to start.  They also require "makedefs" but are independent of
 125 "nethack".  They are usually the last programs made, but since they are
 126 much smaller they may be more tractable when first arguing with the include
 127 files.  These programs create binary data files that "nethack" uses to
 128 guide its dungeon creation.
 129
 130      3.1        Makefiles
 131
 132         This distribution provides makefiles for several kinds of systems.
 133 There are joint makefiles for the various varieties of UNIX, makefiles for
 134 MSDOS, a makefile for NT, and so on.  You may have to create a new
 135 makefile for your specific machine.  You may even have to translate some
 136 makefiles into a form more congenial to your system.  If possible, however,
 137 add to one of those provided.
 138
 139      3.2        termcap.c
 140
 141         If your system wants to use tty windowing and it doesn't run off
 142 of a termcap or terminfo database, you may have to put the appropriate
 143 terminal control strings into termcap.c.  This has already been done for
 144 MSDOS, and these mods can be used as an example.  You can also consider
 145 using the termcap code from sys/share/tclib.c or sys/share/termcap.uu,
 146 especially if your system supports multiple kinds of terminals.
 147
 148      3.3        main.c
 149
 150         You may need to create a new "main.c" module.  If you do, call it
 151 [OS]main.c where the [OS] is replaced with the name of the OS you are porting
 152 to.  This file contains the mainline module, which reads options from the
 153 command line (or wherever) and processes them.  It also contains various
 154 functions associated with game startup.
 155
 156      3.4        tty.c
 157
 158         You may need to create a new "tty.c" module.  If you do, call it
 159 [OS]tty.c where the [OS] is replaced with the name of the OS you are porting
 160 to.  This file contains the routines that configure the terminal/console
 161 for raw I/O, etc.
 162
 163      3.5        unix.c
 164
 165         You may need to create a new "unix.c" module.  If you do, call it
 166 [OS]unix.c where the [OS] is replaced with the name of the OS you are porting
 167 to.  This file contains some OS dependencies concerning time and filename
 168 creation.
 169
 170
 171         An object of the NetHack development project is to get the game
 172 working on as many different types of hardware and under as many different
 173 operating systems as is practical.  Any assistance will be appreciated.