Language:	English

Caution	Please make sure you are able to compile an unmodified version of The Powder Toy before attempting to make your own modifications. This will help people to assist you with potential problems.

Tested MacOS Versions

• 10.15
• 11.5
• 12.5
• 26.3

Required environment setup

• install Homebrew (get it here)
• in a terminal, execute the following commands

brew install pkg-config luajit fftw sdl2 meson ninja bzip2 jsoncpp libpng
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 setup build-debug
cd build-debug
meson compile

• make sure Meson is using Homebrew's Clang (look for clang in the log the setup step prints)
• 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 meson compile again; if it says "no work to do", everything worked fine
• if you get something along the lines of meson.build:110:2: ERROR: Include dir /usr/include does not exist, or if Meson otherwise complains about bzip2, see Elusive bzip2
• at this point, running TPT from the prompt should be possible

./powder

Next Steps

No matter the platform you are compiling for or on, these are the next steps that should be taken to update your binary after making changes, optimizing the build, and creating a release version.

Updating the binary

Now that you have successfully built The Powder Toy for the first time, you will probably want to change things in the code. Any changes made will require a rebuild of the binary. Once the binary is rebuilt, it should reflect your changes

You can rebuild the binary with the following command in the same prompt you executed it the last time:

meson compile

You will have to do this every time you make changes and want the binary to reflect those changes.

Optimized builds

So far, you have been building "debug" binaries. These make debugging significantly easier than "optimized" builds, but they also offer less performance. You can instead build an "optimized" 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 an optimized binary, navigate back to the root of the repository in your prompt and create a new build site with Meson, then build again

cd [whatever parameters that take you to your repositories, see above]
cd The-Powder-Toy
meson setup -Dbuildtype=debugoptimized build-optimized
cd build-optimized
meson compile

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

Release builds

Both the debug and optimized 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). If you are a mod author, please make sure you are not shipping such binaries, as your users are used to TPT not depending on anything and thus are unlikely to have experience with installing these libraries on their own.

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 release binary, navigate back to the root of the repository in your prompt and create a new build site with Meson (see NOTE below!), then build again

meson setup -Dbuildtype=release -Dstatic=prebuilt build-release
cd build-release
meson compile

The "release" buildtype is identical to the "debugoptimized" buildtype, but it produces binaries without debug info. Debug info in static builds can take hundreds of megabytes, because it includes all the debug info from statically linked libraries. Unless you want to separate debug info later for some reason, it is best to get rid of it at compile time. Note that while debugoptimized builds are "only" very difficult to debug, release builds are virtually impossible.

NOTE: On Windows, if using MSVC, you will also need to add the -Db_vscrt=static_from_buildtype option to the Meson call above, otherwise the resulting binaries will be dynamically linked against the MSVC runtime (vcruntime.dll and similar).

meson setup -Dbuildtype=release -Dstatic=prebuilt -Db_vscrt=static_from_buildtype build-release
cd build-release
meson compile

NOTE: On Windows, if using MinGW, you will also need to add the -Dcpp_link_args="['-static','-static-libgcc','-static-libstdc++']" option to the Meson call above, otherwise the resulting binaries will be dynamically linked against the GCC runtime (libgcc_s_seh-1.dll and similar).

meson setup -Dbuildtype=release -Dstatic=prebuilt -Dcpp_link_args="['-static','-static-libgcc','-static-libstdc++']" build-release
cd build-release
meson compile

Note though that even such static builds will not be "fully static", as they will still import functions from msvcrt.dll. This is fine though, as this library is present on every modern install of Windows.

NOTE: On Windows, if using MinGW, -Db_lto=true is known to break static builds; use this setting at your own risk. The Meson configuration will throw a warning upon detecting this setting.

It used to work, but it broke

Each platform has its own set of quirks that need to be worked around (mostly looking at you, microsoft and apple). Fortunately, our build system takes care of most of these. Unfortunately, the workarounds come in the form of upgrades to the build system, which are not installed automatically, and even if they are, affected build sites may need to be reconfigured manually. If you had at some point gotten TPT to build successfully, but since then your build sites somehow broke, you can try one of the following methods to fix them.

The most straightforward way to fix a single build site is to reconfigure it. To check if this worked, try running meson compile.

cd [whatever parameters that take you to your repositories, see above]
cd The-Powder-Toy
meson setup --reconfigure --wipe build-debug # or whatever you named your build site
cd build-debug
meson compile

You will have to do this with every broken build site.

If this does not help, you can upgrade pip, Meson and Ninja. On Linux and MacOS, this is done through the package manager. On Windows, run this in an elevated command prompt:

python -m pip install --upgrade pip # if you get "No module named pip", try python3
python -m pip install --upgrade meson ninja

Once you are done with this, reconfigure your build sites (see above).

If this does not solve the problem, we highly recommend starting over again from a clean build by following the steps outlined in the compiling guide. You do not need to clone the repository again, since you already cloned the repository earlier in this guide and it will remain there until deleted.

In fact, this is where your changes to TPT are stored, so you should never delete it. Deleting your local clone of the repository never solves any problem, it only results in loss of code. Do not even consider doing it.

As a last resort, you can ask the community on the forum.

Builds 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 setup -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 meson compile, 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

Name	Type	Description
static	one of none, system, prebuilt	Build statically using libraries present on the system (system) or using prebuilt libraries official builds use (prebuilt)
lto	boolean	Link-time optimization, mostly a wrapper around the b_lto built-in option
beta	boolean	Beta build
ignore_updates	boolean	Don't show notifications about available updates
can_install	one of no, yes, yes_check, auto	Disable (no) or enable (yes) setting up file and URL associations, or even offer to do it at startup (yes_check)
shared_data_folder	boolean	Handle the shared data folder, e.g. automatically chdir over to it and offering migration to it
http	boolean	Enable HTTP via libcurl
snapshot	boolean	Snapshot build
mod_id	integer	Mod ID, used on the Starcatcher build server, the build server will compile for all platforms for you and send updates in-game, see jacob1 to get a mod ID
lua	one of none, lua5.1, lua5.2, luajit, auto	Lua library to use
x86_sse	one of none, sse, sse2, sse3, sse4.1, sse4.2, avx, avx2, avx512, auto	Enable SSE (available only on x86)
build_powder	boolean	Build the game
build_render	boolean	Build the thumbnail renderer
build_font	boolean	Build the font editor
server	string	Simulation server
static_server	string	Static simulation server
update_server	string	Update server, only used by snapshots and mods, see snapshot and mod_id
workaround_noncpp_lua	boolean	Allow linking against a non-C++ system Lua
workaround_elusive_bzip2	boolean	Find bzip2 via the compiler and its built-in library directories, rather than via pkg-config or similar
workaround_elusive_bzip2_lib_name	string	bzip2 library name, see workaround_elusive_bzip2
workaround_elusive_bzip2_lib_dir	string	bzip2 library directory, see workaround_elusive_bzip2
workaround_elusive_bzip2_include_name	string	bzip2 header name, see workaround_elusive_bzip2
workaround_elusive_bzip2_include_dir	string	bzip2 header directory, see workaround_elusive_bzip2
workaround_elusive_bzip2_static	boolean	bzip2 static setting, see workaround_elusive_bzip2
tpt_libs_vtag	string	tpt-libs vtag override, only used for tpt-libs development
package_mode	string	Package mode override, only used by official builds, see prepare.py
android_keystore	string	Path to Java keystore for signing an APK, only used for Android development
android_keyalias	string	Signing key alias for signing an APK, only used for Android development
app_name	string	App name, used for desktop integration and the window title, change if you work on a mod
app_comment	string	App comment, used for desktop integration, change if you work on a mod
app_exe	string	App executable name, used for desktop integration, change if you work on a mod
app_id	string	App ID, a D-Bus well-known name, used for desktop integration, change if you work on a mod
app_data	string	App data directory name, do not change even if you work on a mod, only if you know what you are doing
app_vendor	string	App vendor prefix, used for desktop integration, do not change even if you work on a mod, only if you know what you are doing
enforce_https	boolean	Enforce encrypted HTTP traffic, may be disabled for debugging
secure_ciphers_only	boolean	Use only secure ciphers for encrypted HTTP traffic, please review cipher list before enabling
prepare	boolean	Used by ghactions workflows, not useful otherwise
render_icons_with_inkscape	feature	Render icons with Inkscape (inkscape binary needs to be in PATH)
resolve_vcs_tag	one of no, static_release_only, yes	Enable VCS tag resolution, introduces an always-stale custom target
platform_clipboard	boolean	Enable platform clipboard, allows copying simulation data between different windows
use_bluescreen	one of no, yes, auto	Show blue error screen upon unhandled signals and exceptions
windows_icons	boolean	Add icon resources to the executable on Windows
windows_utf8cp	boolean	Ask Windows nicely for UTF-8 as the codepage
export_lua_symbols	boolean	Export Lua symbols to enable loading of Lua shared modules
clang_tidy	boolean	Run clang-tidy to lint programming issues