xbuild

xbuild is PEP517 build frontend that has additions and extensions to support cross-compiling wheels for platforms where compilation cannot be performed natively - most notably:

• Android
• Emscripten (WASM)
• iOS

Usage

Creating a cross virtual environment

To create a cross virtual environment, you will need a distribution of Python that has been compiled for Android, Emscripten or iOS. Create a virtual environment for your build platform (i.e., the platform where you will be compiling), then use the xvenv script to convert that virtual environment in to a cross environment.

$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ pip install xbuild
(venv) $ python -m venv x-venv
(venv) $ xvenv --sysconfig path/to/_sysconfig_vars__...json x-venv

You can then activate the cross virtual environment. For example, if x-venv was constructed using an iOS simulator sysconfig vars file (_sysconfig_vars__ios_arm64-iphonesimulator.json), you would see output like:

$ source x-venv/bin/activate
(x-venv) $ python -c "import sys; print(sys.platform)"
ios
(x-venv) $ python -c "import sys; print(sys.implementation._multiarch)"
arm64-iphonesimulator

This should now print the platform identifier for the target platform, not your build platform.

You can also configure xvenv with a _sysconfigdata Python file (e.g., _sysconfigdata__ios_arm64-iphonesimulator.py), instead of the _sysconfig_var JSON file. You'll have to use _sysconfigdata if you're on Python 3.13 (as the JSON format was only introduced in Python 3.14)

If you are in the cross environment, and you need to temporarily convert it back to the build platform, you can do so with the XBUILD_ENV environment variable. For example, if x-venv is an iOS cross environment:

$ source x-venv/bin/activate
(x-venv) $ python -c "import sys; print(sys.platform)"
ios
(x-venv) $ XBUILD_ENV=off python -c "import sys; print(sys.platform)"
darwin

How this works

The cross build environment does not run the target platform binaries on the build platform - it uses binaries for the build platform, but monkey-patches the Python interpreter at startup so that any question asking details about the platform returns details about the target platform. For example, if you create an iOS cross-platform environment on a macOS machine, you'll be using the macOS python.exe; but if you ask for sys.platform, the answer will be ios, not darwin.

Contributing

To set up a development environment:

$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ python -m pip install -U pip
(venv) $ python -m pip install -e . --group dev

Community

xbuild is part of the BeeWare suite. You can talk to the community through:

• @pybeeware on Twitter
• Discord

We foster a welcoming and respectful community as described in our BeeWare Community Code of Conduct.

Contributing

If you experience problems with xbuild, log them on GitHub. If you want to contribute code, please fork the code and submit a pull request.