# Introduction to the buildsystem

## SCons

Pandemonium uses `SCons ( https://www.scons.org/ )` to build. We love it, we are
not changing it for anything else. We are not even sure other build
systems are up to the task of building Pandemonium. We constantly get requests
to move the build system to CMake, or Visual Studio, but this is not
going to happen. There are many reasons why we have chosen SCons over
other alternatives, for example:

-  Pandemonium can be compiled for a dozen different platforms: all PC
   platforms, all mobile platforms, many consoles, and WebAssembly.
-  Developers often need to compile for several of the platforms **at
   the same time**, or even different targets of the same platform. They
   can't afford reconfiguring and rebuilding the project each time.
   SCons can do this with no sweat, without breaking the builds.
-  SCons will *never* break a build no matter how many changes,
   configurations, additions, removals etc. You have more chances to die
   struck by lightning than needing to clean and rebuild in SCons.
-  Pandemonium build process is not simple. Several files are generated by
   code (binders), others are parsed (shaders), and others need to offer
   customization (plugins). This requires complex logic which is easier
   to write in an actual programming language (like Python) rather than
   using a mostly macro-based language only meant for building.
-  Pandemonium build process makes heavy use of cross-compiling tools. Each
   platform has a specific detection process, and all these must be
   handled as specific cases with special code written for each.

So, please try to keep an open mind and get at least a little familiar with it
if you are planning to build Pandemonium yourself.

## Setup

Please refer to the documentation for `doc_compiling_for_android`,
`doc_compiling_for_ios`, `doc_compiling_for_osx`,
`doc_compiling_for_uwp`, `doc_compiling_for_web`,
`doc_compiling_for_windows` and `doc_compiling_for_x11`.

Note that for **Windows/Visual Studio**, you need to use `x86_x64 Cross Tools
Command Prompt for VS 2017` or similar, depending on your install, instead of
the standard Windows command prompt to enter the commands below.

## Platform selection

Pandemonium's build system will begin by detecting the platforms it can build
for. If not detected, the platform will simply not appear on the list of
available platforms. The build requirements for each platform are
described in the rest of this tutorial section.

SCons is invoked by just calling `scons`. If no platform is specified,
SCons will detect the target platform automatically based on the host platform.
It will then start building for the target platform right away.

To list the available target platforms, use `scons platform=list`:

```
    scons platform=list
    scons: Reading SConscript files ...
    The following platforms are available:

        android
        javascript
        server
        windows
        x11

    Please run SCons again and select a valid platform: platform=<string>
```

To build for a platform (for example, x11), run with the `platform=` (or
`p=` to make it short) argument:

```
    scons platform=x11
```

This will start the build process, which will take a while. If you want
SCons to build faster, use the `-j <cores )` parameter to specify how many
cores will be used for the build. Or leave it using one core, so you
can use your computer for something else :)

Example for using 4 cores:

```
    scons platform=x11 -j 4
```

## Resulting binary


The resulting binaries will be placed in the `bin/` subdirectory,
generally with this naming convention:

```
    pandemonium.<platform>.[opt].[tools/debug].<architecture>[extension]
```

For the previous build attempt, the result would look like this:

```
    ls bin
    bin/pandemonium.x11.tools.64
```

This means that the binary is for X11, is not optimized, has tools (the
whole editor) compiled in, and is meant for 64 bits.

A Windows binary with the same configuration will look like this:

```
    C:\pandemonium> dir bin/
    pandemonium.windows.tools.64.exe
```

Copy that binary to any location you like, as it contains the project manager,
editor and all means to execute the game. However, it lacks the data to export
it to the different platforms. For that the export templates are needed (which
can be either downloaded from `pandemoniumengine.org ( https://pandemoniumengine.org/ )`, or
you can build them yourself).

Aside from that, there are a few standard options that can be set in all
build targets, and which will be explained below.


## Tools

Tools are enabled by default in all PC targets (Linux, Windows, macOS),
disabled for everything else. Disabling tools produces a binary that can
run projects but that does not include the editor or the project
manager.

```
    scons platform=<platform> tools=yes/no
```

## Target

Target controls optimization and debug flags. Each mode means:

-  **debug**: Build with C++ debugging symbols, runtime checks (performs
   checks and reports error) and none to little optimization.
-  **release_debug**: Build without C++ debugging symbols and
   optimization, but keep the runtime checks (performs checks and
   reports errors). Official editor binaries use this configuration.
-  **release**: Build without symbols, with optimization and with little
   to no runtime checks. This target can't be used together with
   `tools=yes`, as the editor requires some debug functionality and run-time
   checks to run.

```
    scons platform=<platform> target=debug/release_debug/release
```

This flag appends the `.debug` suffix (for debug), or `.tools` (for debug
with tools enabled). When optimization is enabled (release), it appends
the `.opt` suffix.

## Bits

Bits is meant to control the CPU or OS version intended to run the
binaries. It is focused mostly on desktop platforms and ignored everywhere
else.

-  **32**: Build binaries for 32-bit platforms.
-  **64**: Build binaries for 64-bit platforms.
-  **default**: Build for the architecture that matches the host platform.

```
    scons platform=<platform> bits=default/32/64
```

This flag appends `.32` or `.64` suffixes to resulting binaries when
relevant. If `bits=default` is used, the suffix will match the detected
architecture.

## Custom modules

It's possible to compile modules residing outside of Pandemonium's directory
tree, along with the built-in modules.

A `custom_modules` build option can be passed to the command line before
compiling. The option represents a comma-separated list of directory paths
containing a collection of independent C++ modules that can be seen as C++
packages, just like the built-in `modules/` directory.

For instance, it's possible to provide both relative, absolute, and user
directory paths containing such modules:

```
    scons custom_modules="../modules,/abs/path/to/modules,~/src/pandemonium_modules"
```

Note:


    If there's any custom module with the exact directory name as a built-in
    module, the engine will only compile the custom one. This logic can be used
    to override built-in module implementations.

See also:


    `doc_custom_modules_in_c++`

## Cleaning generated files

Sometimes, you may encounter an error due to generated files being present. You
can remove them by using `scons --clean <options )`, where `<options )` is the
list of build options you've used to build Pandemonium previously.

Alternatively, you can use `git clean -fixd` which will clean build artifacts
for all platforms and configurations. Beware, as this will remove all untracked
and ignored files in the repository. Don't run this command if you have
uncommitted work!

## Other build options

There are several other build options that you can use to configure the
way Pandemonium should be built (compiler, debug options, etc.) as well as the
features to include/disable.

Check the output of `scons --help` for details about each option for
the version you are willing to compile.

### Overriding the build options

#### Using a file

The default `custom.py` file can be created at the root of the Pandemonium Engine
source to initialize any SCons build options passed via the command line:

```
    # custom.py

    optimize = "size"
    module_mono_enabled = "yes"
    use_llvm = "yes"
    extra_suffix = "game_title"
```

You can also disable some of the builtin modules before compiling, saving some
time it takes to build the engine. See `doc_optimizing_for_size` page for more details.

See also:

You can use the online `Pandemonium build options generator ( https://pandemonium-build-options-generator.github.io/ )` 
to generate a `custom.py` file containing SCons options. You can then save this file and place it at the root 
of your Pandemonium source directory.

Another custom file can be specified explicitly with the `profile` command
line option, both overriding the default build configuration:

```
    scons profile=path/to/custom.py
```

Note: Build options set from the file can be overridden by the command line options.

It's also possible to override the options conditionally:

```
    # custom.py

    import version

    # Override options specific for Pandemonium 3.x and 4.x versions.
    if version.major == 3:
        pass
    elif version.major == 4:
        pass
```

#### Using the SCONSFLAGS

`SCONSFLAGS` is an environment variable which is used by the SCons to set the
options automatically without having to supply them via the command line.

For instance, you may want to build Pandemonium in parallel with the aforementioned
`-j` option for all the future builds:

bash Linux/macOS

``` export SCONSFLAGS="-j4" ```

bat Windows (cmd)

``` set SCONSFLAGS=-j4 ```

powershell Windows (powershell)

``` $env:SCONSFLAGS="-j4" ```

## Export templates

Official export templates are downloaded from the Pandemonium Engine site:
`pandemoniumengine.org ( https://pandemoniumengine.org/ )`. However, you might want
to build them yourself (in case you want newer ones, you are using custom
modules, or simply don't trust your own shadow).

If you download the official export templates package and unzip it, you
will notice that most files are optimized binaries or packages for each
platform:

```
    android_debug.apk
    android_release.apk
    webassembly_debug.zip
    webassembly_release.zip
    linux_server_32
    linux_server_64
    linux_x11_32_debug
    linux_x11_32_release
    linux_x11_64_debug
    linux_x11_64_release
    osx.zip
    version.txt
    windows_32_debug.exe
    windows_32_release.exe
    windows_64_debug.exe
    windows_64_release.exe
```

To create those yourself, follow the instructions detailed for each
platform in this same tutorial section. Each platform explains how to
create its own template.

The `version.txt` file should contain the corresponding Pandemonium version
identifier. This file is used to install export templates in a version-specific
directory to avoid conflicts. For instance, if you are building export templates
for Pandemonium 3.1.1, `version.txt` should contain `3.1.1.stable` on the first
line (and nothing else). This version identifier is based on the `major`,
`minor`, `patch` (if present) and `status` lines of the
`version.py file in the Pandemonium Git repository ( https://github.com/pandemoniumengine/pandemonium/blob/master/version.py )`.

If you are developing for multiple platforms, macOS is definitely the most
convenient host platform for cross-compilation, since you can cross-compile for
almost every target (except for UWP). Linux and Windows come in second place,
but Linux has the advantage of being the easier platform to set this up.