| blob | 1abba0d93167980fedc5ab47edb8cb8434d502b3 |
1 NetHack Porting Guidelines v 3.7 2023-04-23
4 1.0 Introduction
6 This document goes through the steps required to port NetHack to a
7 new machine, with the intention of compiling natively on that machine. If
8 you are cross-compiling for one platform on another, it is suggested that
9 you read Cross-compiling.
11 The basic steps in porting the program using a native compiler are:
13 1. Get the code onto your build machine. The parts of the current
14 directory setup you definitely need include src (NetHack code
15 shared by all systems), include (include files), util (code
16 for utility programs), and dat (various data files). The
17 documentation in doc is strongly recommended. You already
18 have the files in the top directory since you're reading this
19 one. :-)
21 If you will be cross-compiling for your target platform on
22 a different platform, you may want to read Cross-compiling
23 in the Top folder as well.
25 A full list of the distribution files and their associated
26 OSes may be found in the top-level file "Files".
28 If your machine uses an OS already supported, you need the sys
29 subdirectory for that OS and possibly sys/share. Otherwise,
30 get the closest match (say sys/msdos for single-tasking OSes
31 and sys/unix for multi-user OSes, along with sys/share, if
32 nothing else comes to mind). You may want others for
33 comparison.
35 If your machine uses a windowing system already supported,
36 you need the win subdirectory for that system (or the
37 appropriate sys subdirectory if the windowing system was
38 previously considered restricted to one OS) and possibly
39 win/share.
41 2. Modify the appropriate include files to customize NetHack to
42 your system. You may need to add a new OS-specific "*conf.h"
43 file (see unixconf.h, windconf.h, pcconf.h, etc. as examples).
45 3. If your machine uses a new OS instead of a variant of existing
46 OSes, add a new sys subdirectory. Add, if required, a OS-
47 specific copy of "main.c", "tty.c" and "unix.c". Possibly
48 add an OS-specific library (see "msdos.c" and "tos.c" as
49 examples) to provide functions NetHack wants and your OS lacks.
51 4. If your machine uses a new windowing system, follow doc/window.txt
52 carefully. Put files implementing these routines in a win or
53 sys subdirectory as appropriate.
55 5. If your compilation environment isn't close to one already
56 supported, try starting from the UNIX makefiles. Modify the
57 top level makefile and the src makefile as required. Then run
58 an initial compile. You are bound to get some errors. You
59 should be able to fix them in a fairly simple fashion. If
60 things seem to be getting too complex, take a step back, and
61 possibly send us some mail. We might be able to help.
63 6. Mail all of your fixes to us in a contextual form so that we can
64 easily integrate them into the code, or fork the NetHack
65 repository on GitHub and issue a pull-request for your changes.
67 One general rule of thumb exists. Always add code. Don't delete
68 somebody else's code for yours -- it won't work on their machine if you do.
69 Always add your OS specific code inside #ifdef / #else / #endif constructs
70 so that it will be able to be folded back into the original code easily.
73 2.0 Include Files
75 2.1 config.h
77 The file "config.h" is a master configuration file that determines
78 the basic features of the game, as well as many of the security options.
79 It is intended that end users configure the game by editing "config.h" and
80 an appropriate "*conf.h" file, so any #defines for individual preferences
81 should be added to those files. OS-specific #defines that are not intended
82 to be changed should also go in "*conf.h"; try to find the most appropriate
83 place for other #defines.
85 The following sections may require modification:
87 - Section 1: OS and window system selection.
88 You may have to put a #define for your OS here.
89 If your OS is yet another UNIX variant, put the
90 #define in unixconf.h instead.
91 An unfortunately large amount of stuff shares
92 this section because the #definitions have to
93 be seen before *conf.h is reached. Don't add
94 to this unless necessary.
96 - Section 2: Global parameters and filenames.
97 These will have to be customized to your system.
99 - Section 3: Type definitions and other compiler behavior.
100 These will have to be matched to your compiler.
102 2.2 global.h
104 This file defines things specific to NetHack that should not
105 require modification by an end user. For a new port, you may have to add
106 automatic inclusion of another auxiliary config file (*conf.h) which you
107 wrote for your system.
109 2.3 extern.h
111 If you create any new source modules or new functions in old modules,
112 you must enter the names of the new external references (the functions defined
113 there for external use) in this file.
116 3.0 Source files
118 The first step in getting the game up is to get the "makedefs"
119 program running. This program is used to create configuration-specific
120 files for the game.
122 Once "makedefs" has been built, the rest of the game can be compiled.
123 You may have to create an OS-specific module to handle things you want to
124 use, like a mouse or a ram-disk.
126 3.1 Makefiles
128 This distribution provides makefiles for several kinds of systems.
129 There are joint makefiles for the various varieties of UNIX, makefiles for
130 MSDOS, a makefile for NT, and so on. You may have to create a new
131 makefile for your specific machine. You may even have to translate some
132 makefiles into a form more congenial to your system. If possible, however,
133 add to one of those provided.
135 3.2 termcap.c
137 If your system wants to use tty windowing and it doesn't run off
138 of a termcap or terminfo database, you may have to put the appropriate
139 terminal control strings into termcap.c. You can also consider using the
140 termcap code from sys/share/tclib.c or sys/share/termcap.uu, especially if
141 your system supports multiple kinds of terminals. Alternatively, you can
142 define NO_TERMS and provide alternative screen handling in a
143 platform-specific module. That has already been done for MSDOS and for
144 the Windows console, and those mods can be used as an example.
146 3.4 tty.c
148 You may need to create a new "tty.c" module. If you do, call it
149 [OS]tty.c where the [OS] is replaced with the name of the OS you are porting
150 to. This file contains the routines that configure the terminal/console
151 for raw I/O, etc.
153 3.5 unix.c
155 You may need to create a new "unix.c" module. If you do, call it
156 [OS]unix.c where the [OS] is replaced with the name of the OS you are porting
157 to. This file contains some OS dependencies concerning time and filename
158 creation.
160 An object of the NetHack development project is to get the game
161 working on as many different types of hardware and under as many different
162 operating systems as is practical. Any assistance will be appreciated.
164 Cross-compiling may allow porting of NetHack to a machine where there may
165 be challenges building on the platform directly, and may help maintain a
166 working version of NetHack on that platform. See the file Cross-compiling
167 for more information.
169 4.0 Build Process
171 NetHack requires the following steps to be carried out:
173 4.1. makedefs
175 Compile and link util/makedefs. Run makedefs repeatedly with different command
176 line options to produce several output files that are required for:
177 (a) creation of files, containing information required by,
178 or about the game during its execution, that are stored in a
179 portable, platform-independent way, that need to be inserted
180 into the final game package.
182 Required for complete packaging of the game, but not the C source
183 game compile:
184 util/makedefs -d
185 util/makedefs -r
186 util/makedefs -h
187 util/makedefs -s
189 For reference purposes, but no longer a required prerequisite for the
190 game compile process:
191 util/makedefs -v
192 util/makedefs -o
193 util/makedefs -p
195 4.2. Other utilities
197 Compile and link other utilities such as uudecode, tile-generation
198 utilities, and so forth. Those produce output files for use during the game and
199 need to be included in the packaging of the game.
201 4.3. Lua
203 Compile and link into a library, or obtain a prebuilt Lua library for
204 your platform. Place the Lua source into lib/lua-5.4.6 (or other folder
205 representing an appropriate Lua version); place the compiled Lua library into
206 lib.
208 4.4 Compile NetHack sources
210 Compile the source code of the game, including a suitable
211 regular-expression choice from several options available in sys/share. Pick one
212 that is supported by your OS or that you have obtained a 3rd party library for.
214 4.5 Compile optional window port components into a library
216 If your platform requires 3rd party sources in order to support the
217 window port options that you have chosen, such as curses sources for the curses
218 window port, you may store the sources for that library in a subfolder under
219 lib.
221 4.6. Link the game
223 Link the game to the Lua library, and to any window port support
224 libraries.
226 4.7 Package the game
230 5.0 Design Updates
232 The following design updates were introduced in NetHack 3.7.
234 5.1 Quest text files
236 The quest text files that were formerly converted from their source
237 text by makedefs during the build process, have been replaced by Lua versions
238 and are inserted into the game package for processing by the embedded Lua
239 interpreter during game execution.
241 5.2 Level Compiler
243 There is no longer a build-time level compiler. Instead, the level
244 descriptions have been converted to Lua and are inserted into the game package
245 for processing by the embedded Lua interpreter during game execution.
247 5.3 Dungeon Compiler
249 There is no longer a build-time dungeon compiler. Instead, the dungeon
250 description has been converted to Lua and is inserted into the game package for
251 processing by the embedded Lua interpreter during game execution.
254 5.4 Run-time Options
256 Some of the build and option information that was formerly produced at
257 build-time by makedefs, and contained information about the game platform and
258 options selected during the build of the game, can now be produced at run-time
259 by code within the game itself. That was done to facilitate cross-compiling of
260 NetHack on one platform for game execution on another.
263 # NetHack 3.7 Porting $NHDT-Date: 1643491454 2022/01/29 21:24:14 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.17 $
264 # Copyright (c) 2005 by Michael Allison
265 # NetHack may be freely redistributed. See license for details.