Compiling Freedoom
==================

This document is a general overview of Freedoom's dependencies
required to build it.  See `README` for a description of what Freedoom
'is', and `BUILD-SYSTEM` for the technical details on 'how' Freedoom
is built.

Required software
-----------------

Building the Freedoom IWADs pretty much simply requires the following:

  * 'make': While there is some attempt to keep our Makefiles
    portable, testing does not really happen on anything but
    https://www.gnu.org/software/make/[GNU Make] (patches to fix
    portability are most welcome!).  On non-GNU systems, it might be
    available in a package and binary named as 'gmake'.
  * 'ImageMagick': This is required for generating some of the
    graphics in Freedoom, including constructing text strings for
    certain cases (such as the big font in level titles).  Some newer
    versions of ImageMagick are known to produce
    https://github.com/freedoom/freedoom/issues/41[strange results] on
    certain operations, most notably the title screen graphic having
    funny colors, but nothing major should be wrong.
  * 'Python': Freedoom uses several Python programs in its tree to
    assist with building the IWADs.  Both Python 2.7 and 3.x are fully
    supported.
  * 'DeuTex' 5.0: Freedoom depends on features developed in this
    version of DeuTex and will not build on earlier versions.  It is
    available at https://github.com/Doom-Utils/deutex in source,
    Windows binary, and Ubuntu binary formats.  As of July 2017, this
    version is very recent and may not be widely available in other
    distribution repositories yet.

All or most of this software should already be available in your
operating system's software repository, with the likely exception of
DeuTex, which is easy to build.

Building Freedoom
-----------------

Significant work has been put into making this step easy.  At the top
of the Freedoom source tree, you should be able to simply type `make`
and wait for it to eventually produce the IWAD files in the `wads`
sub-directory.  Parallel make builds are safe too, such as with `make
-j`.

If only interested in a specific IWAD, you can also run `make
wads/freedm.wad`, `make wads/freedoom1.wad`, `make wads/freedoom2.wad`.

As mentioned in the prior section, the Makefile only recieves testing
with the GNU version of Make.  If the primary version of your Make is
not GNU and it fails, try `gmake` instead.

Building on Microsoft Windows
-----------------------------

Freedoom has normally seen all of its development on Unix-like
systems, nevertheless some people like to compile Freedoom on Windows.
This is possible, although complicated by our choice of tooling for
the project.

It may be possible to use regular Windows versions of all the required
software, but https://cygwin.com/[Cygwin] is highly recommended to
recreate the Unix environment on this operating system anyway.  It
will simplify the process of building Freedoom greatly.  The
previously-mentioned https://github.com/Doom-Utils/deutex[DeuTex
repository] will require a C compiler (such as `gcc` or `clang`) to be
installed in order to build.

It is important that you install the Cygwin-specific versions of all
the required software.  Native versions of Make, Python, ImageMagick,
and DeuTex are not likely to interact well with Cygwin versions of the
software.

As Cygwin provides a GNU system and interface on top of Windows, its
command line is (by default) Bash and not `cmd.exe`.  Instructions on
how to use GNU systems and Bash are out of scope of this document.

Optional software
-----------------

  * 'Git': Freedoom is developed using the Git version control system,
    the latest developments can be tracked with it.
  * 'AsciiDoc': The `*.adoc` files are all written in AsciiDoc markup,
    and it can be used to generate HTML versions of all these
    documents.  This is used as part of the `make dist` target, to
    generate the `README.html` file for inclusion with official Zip
    files.
  * 'Zip': The `make dist` target uses Zip to create release archives
    for FreeDM, Phase 1, and Phase 2.  This can also provide an easy
    way to automate generating in-development versions for other
    people.
