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