.. _rust_crate_configuration: =================== Crate Configuration =================== Build Artifacts for ``pyembed`` =============================== The ``pyembed`` crate needs to reference special artifacts as part of its build process in order to compile a Python interpreter into a binary. The most important of these artifacts is a library providing Python symbols. By default, the ``pyembed`` crate's ``build.rs`` build script will run ``pyoxidizer run-build-script``, which will attempt to find a PyOxidizer config file and evaluate its default *build script* target. Using environment variables set by ``cargo`` and by the ``build.rs`` script, artifacts will be placed in the correct locations and ``pyembed`` will be built seemingly like any normal Rust crate. The special build artifacts are generated by resolving a configuration file target returning a :ref:`config_type_python_embedded_resources` instance. In the auto-generated configuration file, the ``embedded`` target returns such a type. Cargo Features to Control Building ================================== The ``pyembed`` crate and generated Rust projects share a set of ``build-mode-*`` Cargo feature flags to control how build artifacts are created and consumed. The features are described in the following sections. ``build-mode-standalone`` ------------------------- Do not attempt to invoke ``pyoxidizer`` or find artifacts it would have built. It is possible to build the ``pyembed`` crate in this mode if the ``rust-cpython`` and ``python3-sys`` crates can find a Python interpreter. But, the ``pyembed`` crate may not be usable or work in the way you want it to. This mode is intended to be used for performing quick testing on the ``pyembed`` crate. It is quite possible that linking errors will occur in this mode unless you take additional actions to point Cargo at appropriate libraries. ``build-mode-pyoxidizer-exe`` ----------------------------- A ``pyoxidizer`` executable will be run to generate build artifacts. The path to this executable can be defined via the ``PYOXIDIZER_EXE`` environment variable. Otherwise ``PATH`` will be used. At build time, ``pyoxidizer run-build-script`` will be run. A ``PyOxidizer`` configuration file will be discovered using the heuristics described at :ref:`config_locating`. ``OUT_DIR`` will be set if running from ``cargo``, so a ``pyoxidizer.bzl`` next to the main Rust project being built should be found and used. ``pyoxidizer run-build-script`` will resolve the default build script target by default. To override which target should be resolved, specify the target name via the ``PYOXIDIZER_BUILD_TARGET`` environment variable. e.g.:: $ PYOXIDIZER_BUILD_TARGET=build-artifacts cargo build ``build-mode-prebuilt-artifacts`` --------------------------------- This mode tells the build script to reuse artifacts that were already built. (Perhaps you called ``pyoxidizer build`` or ``pyoxidizer run-build-script`` outside the context of a normal ``cargo build``.) In this mode, the build script will look for artifacts in the directory specified by ``PYOXIDIZER_ARTIFACT_DIR`` if set, falling back to ``OUT_DIR``. This directory **must** have a ``cargo_metadata.txt`` file, which will be printed to stdout by the build script to tell Cargo how to link a Python library. ``cpython-link-unresolved-static`` ---------------------------------- Configures the link mode of the ``cpython`` crate to use a static ``pythonXY`` library without resolving the symbol at its own build time. The ``pyembed`` crate or a crate building it will need to emit ``cargo:rustc-link-lib=static=pythonXY`` and any ``cargo:rustc-link-search=native={}`` lines to specify an explicit ``pythonXY`` library to link against. This is the link mode used to produce self-contained binaries containing ``libpython`` and ``pyembed`` code. ``cpython-link-default`` ------------------------ Configures the link mode of the ``cpython`` crate to use default semantics. The crate's build script will find a pre-built Python library by querying the ``python`` defined by ``PYTHON_SYS_EXECUTABLE`` or found on ``PATH``. See the ``cpython`` crate's documentation for more. This link mode should be used when linking against an existing ``libpython`` that can be found by the ``cpython`` crate's build script.