nethack/doc/makedefs.6

.\"DO NOT REMOVE NH_DATESUB .TH MAKEDEFS 6 "Date(%-d %B %Y)" Project(uc)
.TH MAKEDEFS 6 "26 April 2026" NETHACK
.\"DO NOT REMOVE NH_DATESUB .ds Nd Date(%Y)
.ds Nd 2024
.de NB
.ds Nb \\$2
..
.de NR
.ds Nr \\$2
..
.NB $NHDT-Branch: NetHack-5 $
.NR $NHDT-Revision: 1.22 $
.ie \n(.g .ds ^ \(ha
.el       .ds ^ ^
.\" groff and AT&T-descended troffs use different hyphenation patterns.
.\" Don't hyphenate the last word on a page or column, or
.\" before/after last/first 2 characters of a word.
.ie \n(.g .hy 12
.el       .hy 14
.ds Na Kenneth Lorber
.SH NAME
makedefs \- NetHack miscellaneous build-time functions
.SH SYNOPSIS
.B makedefs
{\c
.BR \-o |\c
.BR \-d |\c
.BR \-e |\c
.BR \-m |\c
.BR \-v |\c
.BR \-p |\c
.BR \-q |\c
.BR \-r |\c
.B \-h\c
}
.P
.B makedefs \-\-input
.I file
.B \-\-output
.I file
.BI \-\- command
.SH DESCRIPTION
.B Makedefs
is a build-time tool used for a variety of
.IR nethack (6)
source file creation and modification tasks.
For historical reasons,
.B makedefs
takes two types of command lines.
When invoked with a short option,
the files operated on are determined when
.B makedefs
is compiled.
When invoked with a long option,
the
.B \-\-input
and
.B \-\-output
options are used to specify the files for the
.BI \-\- command.
Each command is only available in one of the two formats.
.SH SHORT COMMANDS
Upper and lower case are both accepted for the short commands.
.TP
.B \-o
Generate
.IR onames.h .
.TP
.B \-d
Generate
.IR data.base .
.TP
.B \-e
Generate
.IR dungeon.pdf .
The input file
.I dungeon.def
is passed through the
same logic as that used by the
.B \-\-grep
command; see the
.B MDGREP FUNCTIONS
section below for details.
.TP
.B \-m
Generate
.I date.h
and
.I options
file.
It will read
.IR dat/gitinfo.txt ,
only if it is present, to obtain 
.B githash=
and 
.B gitbranch=
info and include related preprocessor #defines in
.I date.h
file.
.TP
.B \-p
Generate
.IR pm.h .
.TP
.B \-q
Generate the
.I rumors
file.
.TP
.B \-s
Generate the
.IR bogusmon ,
.IR engrave ,
and
.I epitaph
files.
.TP
.B \-1
Generate the
.I epitaph
file.
.TP
.B \-2
Generate the
.I engrave
file.
.TP
.B \-3
Generate the
.I bogusmon
file.
.TP
.B \-h
Generate the
.I oracles
file.
.SH LONG COMMANDS
.TP
.B \-\-debug
Show debugging output.
.TP
.B \-\-make \fR[\fIcommand\fR]
Execute a short command.
.I Command
is given without preceding dash.
.TP
.BI \-\-input " file"
Specify the input
.I file
for the command (if needed).
If
.I file
is \*(lq\-\*(rq,
.B makedefs
reads the standard input stream.
.TP
.BI \-\-output " file"
Specify the output
.I file
for the command (if needed).
If
.I file
is \*(lq\-\*(rq,
.B makedefs
writes to the standard input stream.
.TP
.B \-\-svs \fR[\fIdelimiter\fR]
Generate a version string to standard output without a trailing newline.
If specified, the delimiter is used between each part of the version string.
.TP
.B \-\-grep
Filter the input
.I file to the output
.IR file .
See the
.B MDGREP FUNCTIONS
section below for information on controlling the filtering operation.
.TP
.B \-\-grep\-showvars
Show the name and value for each variable known to the grep option.
.TP
.B \-\-grep\-trace
Turn on debug tracing for the grep function (
.B \-\-grep
must be specified as well).
.TP
.BI \-\-grep\-defined " symbol"
Exit shell true (0) if
.I symbol
is known and defined, otherwise exit shell false (1).
.TP
.BI \-\-grep\-define " symbol"
Force the value of
.I symbol
to be \*(lqdefined.\*(rq
.I Symbol
must already be known to
.BR makedefs .
.TP
.BI \-\-grep\-undef " symbol"
Force the definition of
.I symbol
to be \*(lqundefined.\*(rq
.I Symbol
must already be known to
.BR makedefs .
.SH MDGREP FUNCTIONS
The
.B \-\-grep
command (and certain other commands) filter their input, on a line-by-line
basis, according to control lines embedded in the input and on information
gleaned from the
.I nethack
configuration.
This allows certain changes such as embedding platform-specific
documentation into the master documentation files.
.P
Rules:
.IP \(bu
The default conditional state is printing enabled.
.IP \(bu
Any line
.I NOT
starting with a caret (\*^) is either suppressed or passed through unchanged
depending on the current conditional state.
.IP \(bu
Any line starting with a caret is a control line; as in C, zero or more spaces
may be embedded in the line almost anywhere (except immediately after the
caret); however the caret must be in column 1.
.IP \(bu
Conditionals may be nested.
.IP \(bu
.I Makedefs
will exit with an error code if any errors are detected; processing will
continue (if it can) to allow as many errors as possible to be detected.
.IP \(bu
Unknown identifiers are treated as both TRUE and as an error.
Note that
.BR \-\-undef " or " #undef
in the
.I nethack
configuration are different from unknown.
.P
Control lines:
.TP
.B
\*^\*^
a line starting with a (single) literal caret
.TP
.B \*^#
a comment
.TP
.B \*^?\fIID
if the
.I ID
is defined set the conditional state to TRUE
.TP
.B \*^!\fIID
if the
.I ID
is not defined set the conditional state to TRUE
.TP
.B \*^:
else; invert the conditional state
.TP
.B \*^.
end the most recent conditional
.\".SH EXAMPLES
.SH AUTHOR
The NetHack Development Team
.SH COPYRIGHT
.\" All troffs and nroffs support `\(co` except Plan 9 nroff, but Plan 9
.\" offers no test for special character availability, and its feature
.\" set too closely resembles DWB 3.3 to test for it.  Use a string with
.\" any nroff-mode formatter not claiming groff compatiblity.
.ds co \(co
.if !\n(.g .if n .ds co (C)\" in principle, should be just "c"
This file is Copyright \*(co \*(Na, \*(Nd for version \*(Nb:\*(Nr.
NetHack may be freely redistributed.
See license for details.