IMPORTANT NOTE: This guide currently only works with the meson branch of the official TPT repo, so you will have to add --branch meson to the git clone invocations below. See the Main Page for guides on building TPT from the master branch.

This is a guide to get you started on coding for The Powder Toy. If you have any questions, just ask in the Development Assistance section on The Powder Toy forums.

Windows (tested on windows 10)

Required environment setup

• install Git (get it here)
  • options should be left as is
• install Python (get it here)
  • it is recommended to allow the installer to add Python to PATH and to disable the path length limit (the latter is offered near the end of the installation process)
• open an elevated command prompt (search for "cmd" the Start Menu, right-click the most sensible result, click "Run as administrator") and execute the following commands

python -m pip install --upgrade pip
pip install meson ninja

• install Visual Studio (get it here)
  • select the Desktop Development workload
  • you really only need "MSVC" and "Windows 10 SDK", so you can uncheck everything else in the list on the right
• find "x64 Native Tools Command Prompt for VS" (or similar, hereafter referred to as "VS prompt") in the Start Menu and execute the following commands
  • it is recommended to pin the resulting window to your taskbar; you will be using this a lot to build TPT

cd /d [wherever you keep your repositories]
git clone https://github.com/The-Powder-Toy/The-Powder-Toy

Building for the first time

• open a VS dev prompt (see above) and execute the following commands

cd /d [wherever you keep your repositories]
cd The-Powder-Toy
meson build-debug
cd build-debug
ninja

• you may see a few warnings throughout all of this, but no errors (if you do at any stage, do not try to skip it; ask us about it on the forum instead)
  • if you are not sure, run "ninja" again; if it says "no work to do", everything worked fine
• at this point, running TPT from the prompt should be possible

powder.exe

MacOS (tested on macos 10.15)

Required environment setup

• install Homebrew (get it here)
• in the next step, xcode-select is used; not that you do not need to install Xcode to run that command
• in a terminal, execute the following commands

xcode-select --install # asks you for confirmation, installs compilers
sudo -H python -m pip install --upgrade pip
sudo -H pip install meson ninja
brew install pkg-config luajit fftw sdl2
cd [wherever you keep your repositories]
git clone https://github.com/The-Powder-Toy/The-Powder-Toy

Building for the first time

• cd to the repository root and execute the following commands

meson build-debug
cd build-debug
ninja

• you may see a few warnings throughout all of this, but no errors (if you do at any stage, do not try to skip it; ask us about it on the forum instead)
  • if you are not sure, run "ninja" again; if it says "no work to do", everything worked fine
• at this point, running TPT from the prompt should be possible

./powder

Linux (tested on ubuntu 20.04)

Required environment setup

• make sure your package lists are up to date (e.g. sudo apt update)
• install git (e.g. sudo apt install git)
• install python (e.g. sudo apt install python3)
• install pip if not present (consult their guide)
• upgrade pip (e.g. sudo -H python3 -m pip install --upgrade pip)
• install meson and ninja if not present (e.g. sudo -H pip install meson ninja)
• optionally, install ccache (e.g. sudo apt install ccache)
• install required libraries (e.g. sudo apt install libluajit-5.1-dev libcurl4-openssl-dev libfftw3-dev zlib1g-dev libsdl2-dev)
  • your package manager may package these under wildly different names; if unsure, skip this step and install whatever libraries meson asks for when setting up the build sites

Building for the first time

• cd to the repository root and execute the following commands

meson build-debug
cd build-debug
ninja

• you may see a few warnings throughout all of this, but no errors (if you do at any stage, do not try to skip it; ask us about it on the forum instead)
  • if you are not sure, run "ninja" again; if it says "no work to do", everything worked fine
• at this point, running TPT from the prompt should be possible

./powder

Next steps (all platforms)

Updating the binary

Now that you have successfully built TPT for the first time, you will probably want to change things in the code. To update the binary, build it again by executing

ninja

in the same prompt you executed it the last time. You will have to do this every time you change something and want the binary to reflect the change.

Release builds

So far, you have been building "debug" binaries. These make debugging significantly easier than "release" builds, but they also offer less performance. You can instead build a "release" binary, which is much more performant, but very difficult to debug. Only use these builds when you are certain that you have no more bugs to take care of. If a bug does appear later on, go back to building debug binaries.

To build a release binary, navigate back to the root of the repository in your prompt and create a new build site with meson, then build with ninja again

cd /d [wherever you keep your repositories]
cd The-Powder-Toy
meson -Dbuildtype=release build-release
cd build-release
ninja

Note that build-debug and build-release directories are independent "build sites", each of which you can update with ninja when you set them as your current directory (by using cd, see the lists of commands above).

Static builds

Both the debug and release configurations above produce "dynamic" binaries, which means they depend on certain components of your system (libraries you have installed with apt on linux or with brew on macos) or files other than powder.exe (DLLs in the same directory as powder.exe on windows). You can get rid of most of these dependencies by building a "static" binary. This way, the binary will depend on very basic components of your system that are very likely to be present. It will also gain a few megabytes and linking it will take longer, which is why you would only do this when you are about to release it to the public.

To build a static binary, navigate back to the root of the repository in your prompt and create a new build site with meson, then build with ninja again

meson -Dbuildtype=release -Dstatic=prebuilt build-release-static
cd build-release-static
ninja

Build options

Build options are passed to Meson at when you set up a build site (see examples above) or at any later time, when the build site is already in use. In both cases, they are passed as command line arguments of the form -D[name]=[value]. For example, to set up a build site that compiles TPT with Lua 5.1 instead of LuaJIT, you would issue the following command

meson -Dlua=lua5.1 build-debug-lua5.1

But you could also take an existing build site and change the relevant build option to do the same

cd build-debug
meson configure -Dlua=lua5.1

The next time you run ninja, everything that needs to be rebuilt as a result of this change will be rebuilt. See the Meson quick guide for more on configuring build sites.

Below is a list of build options our Meson setup supports