272 lines
11 KiB
Plaintext
272 lines
11 KiB
Plaintext
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.doc
|
|
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) additional build steps to follow, including some header
|
|
files: pm.h, onames.h, date.h.
|
|
(b) 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.
|
|
|
|
util/makedefs -v
|
|
util/makedefs -o
|
|
util/makedefs -p
|
|
util/makedefs -z
|
|
util/makedefs -d
|
|
util/makedefs -r
|
|
util/makedefs -h
|
|
util/makedefs -s
|
|
|
|
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.2 (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: 1596498144 2020/08/03 23:42:24 $ $NHDT-Branch: NetHack-3.7 $:$NHDT-Revision: 1.9 $
|
|
# Copyright (c) 2005 by Michael Allison
|
|
# NetHack may be freely redistributed. See license for details.
|