DUMB source HOWTO

This corresponds to DUMB 0.13.3.

Directory structure

There are some rules on how the directories are built.

  1. Libraries are built before programs and other libraries that need them.
  2. Most important programs are built first so that make install lets you play as soon as possible.

Here's the list:

libmissing/
Functions that may be missing from system libraries.
libdumbutil/
Various functions that DUMB uses but which could be used by other, very different programs too.
libdumbwad/
Functions for reading and writing WAD files.
libdumbworldb/
The database of what exists in a level. Doesn't include functions for monster strategy, explosions or such. (Partially implemented.)
libdumbrender/
(Not yet implemented.)
libdumb/
Random stuff that is needed by both DUMB and the utility programs in the package.
intl/
The GNU gettext library. There's nothing DUMB-specific here. So when a new version of gettext is released, you can delete this directory and copy the one in the gettext package here.
dumb/
The game engine itself.
xwad/
Two programs that work under the X Window System.
XWad
A level editor.
XProtoThing
A viewer for protothings. Protothings define what the thing type numbers mean.
ptcomp/
A program that compiles .pt source code to binary lumps that can then be included in WADs.
tool/
Various small utility programs.
dark2trans
A filter for ppm-format pictures. Turns all "dark" pixels to R=0,G=0,B=1 which ppmtodumb recognizes as meaning transparent. The darkness threshold is given as a parameter.
mkdfnt
Turns X11 fonts to pgm-format pictures which can in turn be converted to DUMB's format and put in WADs.
mknulmap
Generates a map containing just an empty room.
mkpnames
Compiles a textual listing to TEXTURE1 and PNAMES lumps.
ppmtodumb
Converts ppm-format pictures to the format DUMB uses.
wadtool
Copies, builds, extracts and concatenates WAD files.
doom/
Sources for doom4dum.wad which lets you play Doom and Doom II with DUMB.
htic/
Sources for htic4dum.wad which lets you play Heretic with DUMB.
test/
Programs to check that the libraries work.
fixed_bm
A fixed-point benchmark. Tests how fast your CPU is.
ldltest
Command-line tests for libdumbworldb. The library used to be called libdumblevel. Hence the name.
po/
Message catalogs for different languages.
docs/
The incomplete documentation.
dos/
Documentation for the DOS port.
maint/
Documentation on maintaining DUMB. This file is here.

Updating the version number

These are the files that you should update when you change DUMB's version number:

The version number is also mentioned in the following files but in such a way that you don't have to change them if you feel lazy:

After changing the version number in configure.in, run make in the build directory. The change will propagate to configure, config.status and config.h and everything will be recompiled.

Adding a new directory

Do the following in the source directory:

  1. Make directory foo.
  2. Create foo/Makefile.am. It can be empty at this phase but I prefer to put one line in it:

    ## Process this file with automake to produce Makefile.in

  3. Add foo in the SUBDIRS definition in the main Makefile.am. The order of the directories matters. So if foo/Makefile.am uses ptcomp, foo must come after ptcomp in the list.
  4. Add foo/Makefile in the AC_OUTPUT statement in configure.in.
  5. Run automake. This generates foo/Makefile.in.
  6. Run autoconf. This updates the configure script.

Then in the build directory:

  1. Run $srcdir/configure with any options you need. This generates foo/Makefile.

    Alternatively, you can run ./config.status --recheck. This gives $srcdir/configure the same options you last gave it. Then you must run ./config.status again, this time without options, because ./config.status --recheck gave $srcdir/configure the --no-create option which caused it to skip the Makefiles and only update config.status.

  2. Run make. This will repeat some of these steps. Don't worry about that.

For experts only: If you feel particularly smart today, you can analyze the Makefiles and find out which files to touch to avoid the unnecessary and superfluous operations. Then you could even add a new target in Makefile.am to do all this.

Adding a new source file

Copy the boilerplate from docs/maint/template.c, or use docs/maint/dumb-autoins.el which does this (and more) automatically.

Add the name of the file to SOURCES in the Makefile.am of that directory. Or if that isn't appropriate, add it to EXTRA_DIST instead.

When finished with the directory, change to the root of the build tree and run "make update-po". This scans files for translatable strings and updates po/*.po files.

Kalle O. Niemitalo <tosi@stekt.oulu.fi>