Building the SLUDGE engine
**************************

   We build the engine with CMake 3.24 or later, on Linux, macOS and
Windows:

     cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
     cmake --build build

   The engine uses SDL 3, libogg, libvorbis, libpng, DUMB and, for movies,
libvpx. By default, CMake uses the versions installed on the system and
builds from source those that it does not find. On Debian and Ubuntu, the
packages are libvorbis-dev, libpng-dev, libdumb1-dev and libvpx-dev, and
libsdl3-dev where it exists.

   You can change the build with these options.

     -DSLUDGE_BUNDLED_DEPS=ON   Build every library from source and link it
                                statically, for an executable that runs on
                                its own.
     -DSLUDGE_MOVIES=OFF        Leave out movie support and libvpx.
     -DSLUDGE_GLES2=ON          Draw with OpenGL ES 2.0 instead of OpenGL.
     -DSLUDGE_DEVICE=<device>   Build for the OpenPandora, the Raspberry Pi
                                or an ODROID, with OpenPandora, RaspberryPi
                                or ODROID. We then draw with OpenGL ES 2.0,
                                and on the OpenPandora, we always show the
                                game in full screen.
     -DSLUDGE_TESTS=OFF         Leave out the tests. We build them by
                                default, and you run them with
                                `ctest --test-dir build'.
     -DSLUDGE_DEVKIT=OFF        Leave out the Dev Kit, which we build by
                                default on Linux (see below).
     -DSLUDGE_ENGINE=OFF        Leave out the engine, for example to build
                                only the Dev Kit.
     -DSLUDGE_DOC=ON            Install the documentation and the example
                                projects.

   On macOS, build each architecture separately, for example with
-DCMAKE_OSX_ARCHITECTURES=x86_64, and combine the executables with lipo.
With packaging/macos/make-app.sh, we make an application bundle around
the engine.

   On Windows, we build with MSYS2 and MinGW. For 32-bit Windows, from
Windows XP on, we cross-compile on Linux with
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/mingw-i686.cmake and
-DSLUDGE_BUNDLED_DEPS=ON. For that, the MinGW-w64 compilers of the win32
thread model and nasm are required (g++-mingw-w64-i686-win32 and nasm on
Debian and Ubuntu).

   Run the engine with the game data file as its argument, for example
`build/sludge-engine gamedata.slg'. Run `build/sludge-engine --help' for
the options.

Making the release packages
***************************

   In .github/workflows/build.yml, we build and test the engine on Linux,
macOS and Windows. For a version tag, such as 2.3.0, we publish a release
with two kinds of packages for macOS and Windows: OpenSLUDGE, the engine
alone, and Out Of Order, the engine with the game Out Of Order, and with
the source tarball, sludge-<version>.tar.gz. We make the packages with the
scripts in the packaging folder.

     get-out-of-order.sh        Download the data file of Out Of Order from
                                the Ubuntu archive and check its hash.
     windows/make-zips.sh       Make the zips of OpenSLUDGE and of Out Of
                                Order for Windows.
     macos/make-app.sh          Make a macOS application bundle, with or
                                without a game.
     macos/sign-app.sh          Sign a macOS application bundle.
     make-tarball.sh            Make the source tarball with git archive,
                                without the files marked export-ignore in
                                .gitattributes.

   Out Of Order is freeware, and anyone may give it away together with its
readme and licence. We change nothing in the game, and only add a
controller mapping for it, packaging/out-of-order/controller.ini. To
publish only OpenSLUDGE, leave out the Out Of Order zips and apps in the
workflow. In the tests of the workflow, we play the opening of Out Of
Order, so keep get-out-of-order.sh for those.

Building the SLUDGE Development Kit
***********************************

Windows and Mac OS X
====================

   So far, we build the Dev Kit with GTK 3 only on Linux. The Windows
installer script, sludge.nsi, is for the earlier Dev Kit with GTK+ 2.16
and GtkGLExt, and the Xcode project in the "Mac Dev Kit" directory is
for Mac OS X 10.4, so we cannot build the current Dev Kit with either of
them.

Linux
=====

   Dependencies of the OpenSLUDGE Dev Kit are GTK 3 (>= 3.20), libepoxy
and libpng. We draw the views of the floor maker, the z-buffer maker and
the sprite bank editor with OpenGL 3.2.

   On Debian and Ubuntu the corresponding packages are libgtk-3-dev,
libepoxy-dev and libpng-dev.

   On Linux, CMake builds the Dev Kit together with the engine, with the
commands at the top of this file. To build and install only the Dev Kit,
run

     cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DSLUDGE_ENGINE=OFF
     cmake --build build
     sudo cmake --install build

   Add -DSLUDGE_DOC=ON to install the documentation too. For the
documentation only, use -DSLUDGE_ENGINE=OFF -DSLUDGE_DEVKIT=OFF
-DSLUDGE_DOC=ON.

   With `ctest --test-dir build', we also draw the views of the floor
maker, the z-buffer maker and the sprite bank editor offscreen and compare
them with the reference images in tests/devkit/references. For that,
Mesa's EGL (libegl-mesa0 on Debian and Ubuntu) is required.
