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'.
  * '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.
  * 'Pillow': A Python image manipulation module that provides the
    features we need for scaling and composing various graphics of the
    game.
  * '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 and
    Windows binary formats.  As of July 2017, this version is very
    recent and may not be widely available in Unix 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 systems,
nevertheless some people like to compile Freedoom on Windows.  This is
possible, although complicated by our choice of tooling for the
project.

GNU environments for Windows such as https://cygwin.com/[Cygwin],
http://www.msys2.org/[MSYS2], or
https://blogs.msdn.microsoft.com/wsl/[WSL] provide sufficient shell
capabilities to build Freedoom.  The dependencies listed previously
for Freedoom apply just as well to a Windows environment.

Instructions on how to use a GNU system and shell 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.
