Advanced compilation guide (for developers)

This guide assumes you have followed along the basic compilation instructions already.

The usual pip install . is good if your goal is to install pygame-ce once, but if you are contributing code to pygame-ce you will want to repeatedly make minor changes to the codebase, run an install and test your changes. The problem is that pip install . can be slow, because this command builds the codebase in an isolated venv, where caching cannot be employed.

For getting around it, we can pass --no-build-isolation to pip. This makes pip not use a virtual environment internally and as a result, now pip cannot handle build-time dependencies automagically: you have to now manually install those.

To do this you have to install the modules mentioned in the requires field under [build-system] in pyproject.toml. At the time of writing of this, the install command works out to

pip install meson-python<=0.16.0 meson<=1.5.1 ninja<=1.11.1.1 cython<=3.0.11 sphinx<=7.2.6

Now that the dependencies are taken care of, we can proceed to make the actual build. We can now make use of the "editable" (-e) install option. This saves you the effort of having to run the install command after every update. Just make your changes in the source tree, and the next time you import pygame the changed files will be re-built (while being much faster than having to do a full re-build).

Then, we will set a "build directory" (using the build-dir option) - the folder where meson will install stuff, to .mesonpy-rel. Finally, the install command looks like

pip install -e . --no-build-isolation -Cbuild-dir='.mesonpy-rel'

Making a debug build

If you intend to use gdb or similar tools for debugging, you will need to build pygame with debug symbols turned on, and optimizations turned off. Fortunately, it is just one flag away: the modified command you have to run is

pip install -e . --no-build-isolation -Cbuild-dir='.mesonpy-dbg' -Csetup-args='-Dbuildtype=debug'

Build-system notes

The updated build system that is used by default is based on meson-python and you will find that it's well documented here.

The legacy setup.py based build system is still around for now, though it may be removed in the long term. In a few cases, you may need to use it (e.g if you are making android or emscripten/wasm builds) and that is done by invoking setup.py directly.

Common issues and corresponding fixes

Make sure you are using a recent-enough pip version

• This guide may use pip features that are not available on the older releases.
• Some older pip versions may throw errors like "pip fails to find meson" or "mesonpy is missing an attribute".