NetHack Porting Guidelines v 3.7 2023-04-23

1.0 Introduction

This document goes through the steps required to port NetHack to a

new machine, with the intention of compiling natively on that machine. If

you are cross-compiling for one platform on another, it is suggested that

you read Cross-compiling.

The basic steps in porting the program using a native compiler 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, windconf.h, pcconf.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.

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. 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. Alternatively, you can

define NO_TERMS and provide alternative screen handling in a

platform-specific module. That has already been done for MSDOS and for

the Windows console, and those mods can be used as an example.

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.8 (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 embedded 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 embedded 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.