Using Cargo with PyOxidizer Source Checkouts

PyOxidizer’s source repository consists of multiple Rust projects/crates. At the root of the repository is a Cargo.toml defining a workspace consisting of all these crates.

Important

Building various Rust crates from source can be extremely brittle and a top-level cargo build will likely encounter multiple build failures.

If you want to run cargo from a PyOxidizer source checkout, you will likely want to limit the invocation to a single crate at a time to ensure things can build.

The following sections detail how to build various crates inside a source checkout.

pyoxidizer Crate

Building the pyoxidizer crate in isolation (e.g. cargo build -p pyoxidizer) should just work, as it is a pretty typical Rust crate.

Perhaps the only special property of this crate is that it defines both a library and an executable. So you may want to limit operations to a specific binary. e.g. cargo build --bin pyoxidizer or cargo test --bin pyoxidizer.

python-packed-resources Crate

This is a standard Rust crate and should always build without issue. e.g. cargo build -p python-packed-resources.

python-packaging Crate

This is a standard Rust crate and should always build without issue. e.g. cargo build -p python-packaging or cargo test -p python-packaging.

pyembed Crate

The pyembed crate provides the bulk of the run-time functionality for binaries embedding Python interpreters. Because the crate needs to consult with a Python interpreter at build time and link against it and because it needs to exchange state with PyOxidizer, its build configuration is… special.

Important

Almost all workspace build failures are somehow related to the pyembed crate.

The pyembed crate defines various features to control how it is built. See Crate Configuration for details.

In its default configuration, a Python 3.8 executable needs to be found on PATH. If said executable can’t be found, you’ll get a No python interpreter found of version 3.* error at build time.

To work around this, add a python3.8 or python3 executable to PATH or run cargo build with the PYTHON_SYS_EXECUTABLE environment variable pointing to a specific Python 3 executable. e.g.

$ PYTHON_SYS_EXECUTABLE=/path/to/python3.8 cargo build -p pyembed

oxidized-importer Crate

This crate is a very small shim around the pyembed crate which builds the pyembed crate in a specific manner so it provides just the functionality needed for oxidized_importer Python Extension.

Because this crate is a thin shim, the caveats that apply to building pyembed apply to it as well.