This is an explanation of the functioning of the Freedoom build system.
Overview
Freedoom is built using deutex, which is a command-line tool for automated building of Doom WAD files. However, multiple different WAD files are built from the Freedoom material. Therefore, the Freedoom build system is more complicated than a "normal" deutex build would otherwise be.
A top-level Makefile controls the build system and executes the appropriate commands to generate the output WAD files. Various intermediate files are generated in the process by scripts. The following diagram illustrates the process:
buildcfg.txt textures/combined.txt | | | ---------- | | cpp | | ---------- | | | textures/(wad)/texture1.txt | | | | ------------------- | | | extract-pnames.py | | | ------------------- | -------- | | | cpp |----- textures/(wad)/pnames.txt | -------- | | | -------------------- | | wadinfo-builder.py | | -------------------- | | | wadinfo.txt | | | -------- | | |----------------------------------- | deutex | | |--------- all other source files (graphics, etc) -------- | wads/(wadname).wad
Output WAD files
The following are the resulting WAD files generated by the build system:
-
freedoom.wad : Resource PWAD file containing all of the Freedoom resources except for the levels.
-
freedoom_levels.wad : Resource PWAD containing the (Doom II) levels.
-
freedoom_sprites.wad : Resource PWAD containing the sprites.
-
freedoom_sounds.wad : Resource PWAD containing the (Doom II) music and sound effects.
-
freedoom_textures.wad : Resource PWAD containing the (Doom II) textures.
-
doom2.wad : Doom II IWAD file.
-
doom1.wad : "Shareware" IWAD file, containing only episode 1 levels, and a reduced set of textures and sprites.
-
doom.wad : "Ultimate" Doom I IWAD file.
-
freedm.wad : FreeDM IWAD file, containing deathmatch levels, and with all monsters replaced by dummy graphics.
Source configuration files
Master configuration file (buildcfg.txt)
deutex is configured using a configuration file typically named wadinfo.txt. In the case of Freedoom, multiple different WADs are built from the common material, with slightly different settings for each. Therefore, a master configuration file named buildcfg.txt is used to generate configuration files for each individual WAD to build.
The buildcfg.txt file is processed using a Python script named simplecpp. This processes files with a syntax similar to the cpp tool (C Preprocessor). Variables are defined on the command line, based on the type of output target desired:
-
DOOM2 : Build for a Doom II WAD.
-
DOOM1 : Build for a Doom I WAD.
-
SHAREWARE : Build for a small IWAD file, similar to the Doom shareware file.
-
ULTDOOM : Include episode four levels.
Texture configuration file (textures/combined.txt)
The texture configuration file is used to generate the texture1.txt file. This is a list of textures that is used by deutex to generate the TEXTURE1 lump that contains Doom’s texture definitions.
Similarly to the build configuration file, different textures are included depending on the output WAD type. The file is processed by the simplecpp script to include the appropriate textures. Command line variables are defined based on the desired build settings:
-
DOOM1 : Include textures that only exist in Doom I.
-
DOOM2 : Include textures that only exist in Doom II.
-
ULTDOOM : Include textures that only exist in Ultimate Doom.
-
SHAREWARE : Only include textures that are needed for the shareware build.
-
FREEDM : Include textures that are needed for FreeDM.
Note that DOOM1 and DOOM2 are not mutually exclusive, and the default for a Doom II build is to include all of the textures for both.
Generated files
The following files are generated automatically by automated scripts during the build process.
texture1.txt
This file contains the texture definitions and is used by deutex to generate the TEXTURE1 lump. It is generated automatically from textures/combined.txt as a template.
Several different texture1.txt files are generated for the different WAD files that are built:
Filename | WAD file | CPP variables |
---|---|---|
textures/doom2/texture1.txt | doom2.wad | DOOM1, DOOM2 |
textures/doom/texture1.txt | doom.wad | DOOM1, ULTDOOM |
textures/shareware/texture1.txt | doom1.wad | SHAREWARE |
textures/freedm/texture1.txt | freedm.wad | FREEDM |
pnames.txt
This file contains a list of all of the patches used in the texture definition file (texture1.txt). It is generated by the extract-pnames.py script.
Several different pnames.txt files are generated for the different WAD files that are built:
Filename | WAD file |
---|---|
textures/doom2/texture1.txt | doom2.wad and resource WADs |
textures/doom/texture1.txt | doom.wad |
textures/shareware/texture1.txt | doom1.wad |
textures/freedm/texture1.txt | freedm.wad |
wadinfo.txt
This is the auto-generated deutex configuration file, built from the buildcfg.txt template. It includes the PNAMES list from pnames.txt.
Several different wadinfo.txt files are generated for the different WAD files that are built:
Filename | WAD file | CPP variables |
---|---|---|
wadinfo.txt | Resource WAD files | DOOM2 |
wadinfo_iwad.txt | doom2.wad | DOOM2 |
wadinfo_sw.txt | doom1.wad | SHAREWARE |
wadinfo_freedm.txt | freedm.wad | FREEDM |
wadinfo_ult.txt | doom.wad | DOOM1, ULTDOOM |
wadinfo.txt differs from the others in that the -dummy option is not passed to the wadinfo-builder.py script.
Auxiliary scripts
The build system uses a number of auxiliary scripts in order to generate the necessary configuration files for the build. These are written in Python.
simplecpp
This script implements a subset of the syntax of the C preprocessor. It accepts #ifdef … #endif blocks to conditionally include sections of the input file in the output file. This is used when generating the wadinfo.txt and texture1.txt files to conditionally include certain resources depending on the type of WAD file being built.
The simplecpp script is used in preference to the actual cpp preprocessor, firstly so that it is not necessary to install cpp, and secondly because processing with cpp can alter the layout of the output file.
wadinfo-builder.py
This script processes the wadinfo.txt used to build the WAD file, and identifies resources specified in the file that do not yet exist. This is to deal with the fact that Freedoom is incomplete and not all of the material needed for a complete WAD has yet been submitted.
Different strategies are used to cope with these missing resources depending on the WAD file being built. For IWAD builds, dummy resources are substituted for the missing resources (this mode is activated using the -dummy command line parameter). For resource WAD builds, the missing resources are commented out in the output file so that they are missing from the WAD that is built. This is the default behavior.
extract-pnames.py
This script processes the texture file (texture1.txt) and outputs a list of the names of all the required patches. This is used to generate a file named pnames.txt that is included in the wadinfo.txt configuration file in a section named "[patches]".
deutex
deutex is the tool used to generate the WAD files. It processes a file typically named wadinfo.txt, reading files from the following directories to generate the WAD:
-
flats : Floor and ceiling textures.
-
graphics : Graphics for the menu, heads up display and status bar, etc.
-
levels : The levels. Files are named eg. map01.wad or e1m1.wad for Doom II and Doom I levels, with FreeDM levels named eg. dm01.wad.
-
lumps : Miscellaneous lumps.
-
musics : Music files, in MUS or MIDI format.
-
patches : Patch graphics that are used to compose wall textures.
-
sounds : Sound effects, in WAV format.
-
sprites : Graphics for the in-game sprites (monsters, power-ups, weapons, decorations, etc.)
-
textures : Texture definitions.
Idiosyncrasies
deutex is an old tool and has various quirks that must be worked around. Some of them are listed here.
-
The default background color for sprites is magenta. The "standard" background color of cyan is used instead by providing the -rgb 0 255 255 command line parameter.
-
By default, deutex attempts to convert sound effects to 11,025Hz format. To keep the existing sample rate of sound effects, the following command line parameters are provided: -v0 -fullsnd -rate accept
-
deutex does not allow the exact path to the texture1.txt file to be specified; instead, it expects to find the file in textures/texture1.txt. To work around this, a symlink is kept at this location that points to the actual texture1.txt being used. A side effect of this issue is that parallel builds with make are not possible (the -j option).
-
deutex requires an existing IWAD file in order to build WAD files, and includes the contents of the TEXTURE1 lump from the IWAD in any TEXTURE1 lumps it generates. To work around this, a "dummy" IWAD file containing an empty TEXTURE1 lump is contained inside the dummy directory.