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