-
-
Notifications
You must be signed in to change notification settings - Fork 154
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 build caching cannot be employed.
To make the entire process of contributing simpler, there is a helper script at the root of the project: dev.py. This essentially implements shorthand aliases for commands most useful for pygame-ce developers, while automating things like dependency handling in the background.
NOTE: dev.py can install and update packages with pip, you may want to run the command in a venv if you don't want to clutter your global environment or don't want automated changes made to it. The script also comes with a handy --venv flag to create a new venv for you.
The script has a bunch of useful commands and flags, though this doc is only going to focus on the most useful ones. For a complete overview use python dev.py -h to get a general overview on the top level commands and flags, and python dev.py [subcommand] -h to get subcommand specific help.
python dev.py build
Builds and installs pygame in "editable" mode by default. The editable mode 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).
Some useful variants.
-
python dev.py build --debug: Build in debug mode (optimizations disabled and debug symbols enabled) instead of the default release mode. -
python dev.py build --sdl3: Build against SDL3 instead of the default SDL2.
For more flags and more info, do python dev.py build -h
python dev.py docs builds the docs, python dev.py docs --full forces a full generation ignoring the previous build cache.
We have a pre-commit config available, if you want to set up git hooks to automate code formatting. If you can't or don't want to use it, you can use the dev.py substitute: python dev.py format to format the code.
python dev.py lint runs pylint tests on the codebase.
python dev.py stubs runs mypy stubtest and also generates the automated bits of the stubs that we use.
python dev.py test is a simple shorthand for python -m pygame.tests to run all our unit tests. It can also take a list of modules optionally as arguments to run tests on that subset only.
Finally, we have the ultimate short hand of all short hands: python dev.py all. This command will run all of the above commands in the correct order to ensure that any changes made to pygame-ce are ready to go! This is handy to run before submitting your PRs.
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.