mirror of
https://github.com/freedoom/freedoom.git
synced 2025-09-06 10:25:45 -04:00
rename files from *.asc to *.adoc
In a world ravaged by software that determines file type by the last part of the file's name, *.asc is somewhat troublesome given file managers that think these are PGP keys. Also GitHub won't render AsciiDoc without one of a few extensions, at least *.adoc is somewhat clearer and not as obnoxiously long as *.asciidoc
This commit is contained in:
Mike Swanson
parent
4c9c8649dd
commit
88ec3f5884
3 changed files with 3 additions and 3 deletions
279
BUILD-SYSTEM.adoc
Normal file
279
BUILD-SYSTEM.adoc
Normal file
|
|
@ -0,0 +1,279 @@
|
|||
= 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.
|
||||
|
||||
* 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 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue