archives/freedoom
2
0
Fork 0
mirror of https://github.com/freedoom/freedoom.git synced 2025-09-02 07:25:45 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

BUILD-SYSTEM: rewritten document.

Browse source 
Complately rewritten documentation for how the build system works.
Signed-off-by: Simon Howard <fraggle@gmail.com>
This commit is contained in:
Simon Howard 2009-06-18 22:10:06 +01:00
parent 5242dc379f
commit 48b5d40471
1 changed files with 263 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

324
BUILD-SYSTEM
View file

@ -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.