= Build system 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 lumps/textures/textures.cfg │ │ │ ┌───┴────┐ │ │ cpp │ │ └───┬────┘ │ │ │ ┌─────────┴────────┐ │ │ build-textures │ │ └──┬────────────┬──┘ │ │ │ │ pnames.txt texture1.lmp, pnames.lmp │ │ │ ┌───┴────┐ │ │ │ cpp ├───────────┘ │ └───┬────┘ │ │ │ ┌─────────┴──────────┐ │ │ 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: * +freedoom1.wad+: Phase 1, the _Ultimate Doom_ IWAD file. * +freedoom2.wad+: Phase 2, the _Doom II_ IWAD file. * +freedm.wad+: FreeDM IWAD file, containing deathmatch levels == 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. * +ULTDOOM+: Include episode four levels. === Texture configuration file (+lumps/textures/textures.cfg+) The texture configuration file is used to generate the texture lumps. These are +texture1.lmp+ (texture directory), +pnames.lmp+ (list of patch names) and +texture2.lmp+ (Doom I only). They are generated by the +build-textures+ script; deutex's internal texture builder is deliberately not used for compatibility reasons. Similarly to the build configuration file, different textures are included depending on the output WAD type. The file is passed through 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. * +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. === Texture files +texture1.lmp+ is a binary file that contains the texture definitions and is built by the +build-textures+ script from +lumps/textures/textures.cfg+ as a template. +pnames.txt+ contains a list of all of the patches used in the texture definition file (+texture1.txt+). It is generated as an output by the +build-textures+ script. Multiple sets of these files are generated with different configurations for each IWAD file. [frame="topbot",grid="none",options="header"] |=============================================================== | Subdirectory | WAD File | CPP Variables | +lumps/textures/phase1/+ | +freedoom1.wad+ | DOOM1, ULTDOOM | +lumps/textures/phase2/+ | +freedoom2.wad+ | DOOM1, DOOM2 | +lumps/textures/freedm/+ | +freedm.wad+ | FREEDM |=============================================================== === +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: [frame="topbot",grid="none",options="header"] |=============================================================== | Filename | WAD File | CPP Variables | +wadinfo.txt+ | Resource WAD files | DOOM2 | +wadinfo_phase1.txt+ | +freedoom1.wad+ | DOOM1, ULTDOOM | +wadinfo_phase2.txt+ | +freedoom2.wad+ | DOOM2 | +wadinfo_freedm.txt+ | +freedm.wad+ | FREEDM |=============================================================== +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. === +build-textures+ This script processes the texture file (+texture1.txt+) and outputs the binary texture lumps +texture1.lmp+, +texture2.lmp+ and +pnames.lmp+. Also output from the +build-textures+ script is a file named +pnames.txt+ which is simply a text file containing the patches listed in +pnames.lmp+. This is included in the wadinfo.txt file so that all patches listed by the texture directory are automatically included in the IWAD with no need for manual configuration. === +textgen+ Found in +graphics/text+, this script generates various graphics files that are used in the Doom menus and intermission screen. It reads level names from the dehacked lumps. === +playpal.py+ Found in +lumps/cph/misc-lumps+, this script builds the +PLAYPAL+ lump which contains the 256-color palettes used for special effects (injured “red” flash, the green “radiation suit” effect, etc.) === +colormap.py+ Found in +lumps/cph/misc-lumps+, this script builds the +COLORMAP+ lump that is used for the diminished lighting within the game. This script is also reused to generate additional colormaps that can be used for special effects. It has a number of command line options that allow it to do various different colorizing and “fog” effects. === +mkgenmidi+ Found in +lumps/genmidi+, this script builds the +GENMIDI+ lump used for OPL MIDI synthesizer playback. The inputs for this script are a collection of instrument files that are in the standard +SBI+ format for OPL instruments. This lump is essential if you want to play using a classic Adlib or Soundblaster card; these are emulated by several source ports and some people still like to play using emulated OPL for the authentic retro feel. === +gen-ultramid+ Found in +lumps/dmxgus+, this script builds the +DMXGUS+ lump used for GUS MIDI playback. The GUS (Gravis UltraSound) card was a gaming sound card popular in the '90s. As with the +GENMIDI+ lump, few people are still using a real GUS card nowadays, but several source ports emulate them and require this file. == 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. * deutex does not allow the exact path to the +texture1.txt+ file to be specified in the configuration file; this used to be a problem but the Freedoom's texture lumps are now built using a custom script. * 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.