-
-
Notifications
You must be signed in to change notification settings - Fork 152
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'
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'
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.
- 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".