mirror of
https://github.com/freedoom/freedoom.git
synced 2025-09-04 04:25:46 -04:00
BUILD-SYSTEM: rewritten document.
Complately rewritten documentation for how the build system works. Signed-off-by: Simon Howard <fraggle@gmail.com>
This commit is contained in:
Simon Howard
parent
5242dc379f
commit
48b5d40471
1 changed files with 263 additions and 61 deletions
324
BUILD-SYSTEM
324
BUILD-SYSTEM
|
|
@ -1,68 +1,270 @@
|
||||||
NB: This is all out of date now. I need to update it at some point
|
|
||||||
|
|
||||||
COPYING
|
= Build system
|
||||||
The modified BSD license the freedoom material is under
|
|
||||||
ChangeLog
|
|
||||||
List of changes
|
|
||||||
CREDITS
|
|
||||||
List of contributors
|
|
||||||
|
|
||||||
flats
|
This is an explanation of the functioning of the Freedoom build
|
||||||
Floor textures
|
system.
|
||||||
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
|
|
||||||
|
|
||||||
Build system:
|
== Overview
|
||||||
|
|
||||||
Makefile
|
Freedoom is built using 'deutex', which is a command-line tool for
|
||||||
Build makefile. Build everything or just certain bits
|
automated building of Doom WAD files. However, multiple different WAD
|
||||||
build
|
files are built from the Freedoom material. Therefore, the Freedoom
|
||||||
Wrapper script for make. Redirect all stdout and stderr messages
|
build system is more complicated than a "normal" deutex build would
|
||||||
to build.output
|
otherwise be.
|
||||||
|
|
||||||
buildcfg.txt
|
A top-level +Makefile+ controls the build system and executes the
|
||||||
The combined build spec file. Features specific to Doom1/Doom2/
|
appopriate commands to generate the output WAD files. Various
|
||||||
shareware builds are specified with #defines. This file is parsed
|
intermediate files are generated in the process by scripts. The
|
||||||
by cpp (the GNU C PreProcessor) which generates the appropriate
|
following diagram illustrates the process:
|
||||||
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).
|
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.
|
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue