diff --git a/BUILD-SYSTEM b/BUILD-SYSTEM index 32b3e516..5dcbda7c 100644 --- a/BUILD-SYSTEM +++ b/BUILD-SYSTEM @@ -1,68 +1,270 @@ -NB: This is all out of date now. I need to update it at some point -COPYING - The modified BSD license the freedoom material is under -ChangeLog - List of changes -CREDITS - List of contributors += Build system -flats - Floor textures - The files in this directory are symlinks into subdirectories (1 - directory for each author) -flats_hi - See patches_hi. High resolution flats. -graphics - Graphics for menu, heads up display and status bar, etc. -levels - levels. - Currently we have 32 randomly generated slige levels here :) -lumps - miscellaneous lumps. PLAYPAL and COLORMAP are assigned to cph. -musics - musics. -patches - Patches for wall textures. - Organised the same as for flats. -patches_hi - High resolution wall patches. These are in .png format, and are - converted to tga by the build script -sounds - Sounds -sprites - Sprites - We currently have the enemy sprites from Iikka keranens Povdoom in - here, these may be only temporary -textures - Texture definitions - for TEXTURE1 and PNAMES +This is an explanation of the functioning of the Freedoom build +system. -Build system: +== Overview -Makefile - Build makefile. Build everything or just certain bits -build - Wrapper script for make. Redirect all stdout and stderr messages - to build.output +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. -buildcfg.txt - The combined build spec file. Features specific to Doom1/Doom2/ - shareware builds are specified with #defines. This file is parsed - by cpp (the GNU C PreProcessor) which generates the appropriate - wadinfo.txt for the type of wad wanted. The file is also passed - through wadinfo-builder.pl, which comments out all lines which - refer to resources which have not yet been submitted (so the wad - can still be built). +A top-level +Makefile+ controls the build system and executes the +appopriate 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: + +[frame=all] +`---------------------------------.--------------.-------------- +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: + +[frame=all] +`---------------------------------.----------------------------- +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: + +[frame=all] +`-----------------------.--------------------.------------------ +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+ : Miscellaenous 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. + +=== Idiosynchrosies + +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. -wadinfo.txt - The deutex build file for the main build. Do not edit this file - directly; use buildcfg.txt -wadinfo_sw.txt - The deutex build file for the shareware build. Do not edit this - file directly; use buildcfg.txt -wadinfo_iwad.txt - The deutex build file for the iwad build. Do not edit this file - directly; use buildcfg.txt. This is the same as wadinfo.txt except - instead of missing resources being commented out, they are linked - to dummy replacements.