.. _distributions: ===================== Distribution Archives ===================== This project produces tarball archives containing Python distributions. Full Archive ============ The canonical output of this project's build system are ``.tar.zst`` (zstandard compressed tarballs) files. All files within the tar are prefixed with ``python/``. Within the ``python/`` directory are the following well-known paths: PYTHON.json Machine readable file describing this Python distribution. See the ``PYTHON.json File`` section for the format of this file. By convention, the ``build/`` directory contains artifacts from building this distribution (object files, libraries, etc) and the ``install/`` directory contains a working, self-contained Python installation of this distribution. The ``PYTHON.json`` file should be read to determine where specific entities are located within the archive. PYTHON.json File ---------------- The ``PYTHON.json`` file describes the Python distribution in a machine readable manner. This file is meant to be opened by downstream consumers of this distribution so that they may learn things about the distribution without having to resort to heuristics. The file contains a JSON map. This map has the following keys: version Version number of the file format. Currently ``7``. target_triple A target triple defining the platform and architecture of the machine that binaries target. We use Rust's set of defined targets for values. Run ``rustup target list`` to see potential values. Example values are ``x86_64-unknown-linux-gnu``, ``x86_64-unknown-linux-musl``, ``x86_64-pc-windows-msvc``, and ``x86_64-apple-darwin``. (Version 5 or above only.) optimizations String indicating what optimization profile has been applied to the build. Known values include ``debug``, ``noopt``, ``pgo``, ``lto``, and ``pgo+lto``. (Version 5 or above only.) os Target operating system for the distribution. e.g. ``linux``, ``macos``, or ``windows``. (Deprecated in version 5 in favor of ``target_triple``.) arch Target architecture for the distribution. e.g. ``x86`` (32-bit) or ``x86_64`` (64-bit). (Deprecated in version 5 in favor of ``target_triple``.) python_tag The PEP 425 *Python Tag* value. e.g. ``cp38``. (Version 5 or above only.) python_abi_tag The PEP 425 *ABI Tag* value. e.g. ``cp37m``. This may be null if the distribution's platform doesn't expose the concept of an ABI tag. (Version 5 or above only.) python_platform_tag The PEP 425 *Platform Tag* value. e.g. ``linux_x86_64``. (Version 5 or above only.) python_flavor Type of Python distribution. e.g. ``cpython``. (Deprecated in version 5 in favor of PEP 425 tags.) python_implementation_cache_tag Tag used by import machinery to derive filenames for bytecode files. This is the value exposed by ``sys.implementation.cache_tag`` (Version 5 or above only.) python_implementation_hex_version Hexidecimal expression of implementation version. This is the value exposed by ``sys.implementation.hexversion``. (Version 5 or above only.) python_implementation_name Name of Python implementation. This is the value exposed by ``sys.implementation.name``. (Version 5 or above only.) python_implementation_version Array of version components of Python implementation. This is the value exposed by ``sys.implementation.version``. Unlike ``sys.implementation.version``, all elements are strings, not a mix of numbers and strings. (Version 5 or above only.) python_version Version of Python distribution. e.g. ``3.8.2``. python_major_minor_version ``X.Y`` version string consisting of Python major and minor version. (Version 5 or above only.) python_paths Mapping of ``sysconfig`` path names to paths in the distribution. Keys are values like ``stdlib`` and ``include``. Values are relative paths within the distribution. See https://docs.python.org/3/library/sysconfig.html#installation-paths for the meaning of keys. (Version 5 or above only.) python_paths_abstract Mapping of ``sysconfig`` path names with placeholder values. See https://docs.python.org/3/library/sysconfig.html#installation-paths for the meaning of keys. This is equivalent to calling ``sysconfig.get_paths(expand=False)``. (Version 6 or above only.) python_config_vars Mapping of string configuration names to string values. This is equivalent to ``sysconfig.get_config_vars()`` with all values normalized to strings. Many configuration values may represent state as it existed in the build environment and aren't appropriate for the run-time environment on a different system. (Version 6 or above only.) python_exe Relative path to main Python interpreter executable. python_include Relative path to include path for Python headers. If this path is on the compiler's include path, ``#include `` should work. (Deprecated in version 5 in favor of ``python_paths``.) python_stdlib Relative path to Python's standard library (where ``.py`` and resource files are located). (Deprecated in version 5 in favor of ``python_paths``.) python_stdlib_platform_config Relative path to a ``config-`` directory in the standard library containing files used to embed Python in a binary. This is a standard directory present in POSIX Python installations and is not specific to this project. The key may be absent if no platform config directory exists. (Version 5 or above only.) python_stdlib_test_packages Array of strings of Python packages that define tests. (Version 4 or above only.) python_suffixes A map defining file suffixes for various Python file types. Each entry in the map is an array of strings. The map has the following keys. ``bytecode`` Suffixes for bytecode modules. Corresponds to ``importlib.machinery.BYTECODE_SUFFIXES``. e.g. ``[".pyc"]``. ``debug_bytecode`` Suffixes for debug bytecode modules. Corresponds to ``importlib.machinery.DEBUG_BYTECODE_SUFFIXES``. e.g. ``[".pyc"]``. ``extension`` Suffixes for extension modules. Corresponds to ``importlib.machinery.EXTENSION_SUFFIXES``. e.g. ``[".cpython-38-x86_64-linux-gnu.so", ".abi3.so", ".so"]``. ``optimized_bytecode`` Suffixes for optimized bytecode modules. Corresponds to ``importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES``. e.g. ``[".pyc"]``. ``source`` Suffixes for source modules. Corresponds to ``importlib.machinery.SOURCE_SUFFIXES``. e.g. ``[".py"]``. (Version 5 or above only.) python_bytecode_magic_number Magic number to use for bytecode files, expressed as a hexidecimal string. (Version 5 or above only.) libpython_link_mode How `libpython` is linked. Values can be one of the following: `static` Statically linked. `shared` Dynamically linked. (A `libpythonXY` shared library will be part of the distribution.) (Version 5 or above only.) link_mode Alias of ``libpython_link_mode``. (Version 4 or above only. Deprecated in version 5.) python_symbol_visibility Defines how Python symbols are defined in binaries. ``global-default`` (UNIX only.) Symbols are defined as *global* and have *default* binding, making them visible outside their defining component. ``dllexport`` (Windows only.) Symbols are exported via ``__declspec(dllexport)``, making them visible to external libraries. (Version 5 or above only.) python_extension_module_loading Defines support for loading Python extension modules. The value is an array of strings denoting support for various loading mechanisms. Note that downstream consumers reconstructing a new binary from object files or a static library can alter support depending on how that binary is linked. The special values are as follows. ``builtin`` Supports loading of *builtin* extension modules compiled into the binary. (This should always be present.) ``shared-library`` Supports loading of extension modules defined as shared libraries. e.g. from ``.so`` or ``.pyd`` files. (Version 5 or above only.) apple_sdk_canonical_name Optional canonical name of Apple SDK used to build. Should only be present for target triples with ``apple`` in them. The canonical name can be used to find a copy of this SDK on another machine. (Version 7 or above only.) apple_sdk_platform Optional name of the platform of the Apple SDK used to build. Should only be present for target triples with ``apple`` in them. e.g. ``macosx`` (Version 7 or above only.) apple_sdk_version Optional version of the Apple SDK used to build. Should only be present for target triples with ``apple`` in them. If relinking build artifacts, ideally this exact SDK version is used. Newer versions will likely work. Older versions or Clang toolchains associated with older versions may not. (Version 7 or above only.) apple_sdk_deployment_target Optional version of the Apple SDK deployment target used to build. This effectively establishes a minimum version of the target operating system this binary is purportedly compatible with. (Version 7 or above only.) crt_features Describes C Runtime features/requirements for binaries. The value is an array of strings denoting various properties. The special string values are as follows. ``glibc-dynamic`` Binaries link dynamically against glibc. ``glibc-max-symbol-version:N`` Denotes the max symbol version seen in glibc versioned symbols. This effectively advertises the oldest version of glibc that binaries support and indirectly advertises the oldest Linux distributions binaries can run on. ``static`` Binaries link the CRT statically. ``vcruntime:N`` Binaries link against the Microsoft Visual C++ Redistributable Runtime, version ``N``. ``N`` is a string like ``140``, which denotes the version component in a ``vcruntimeXYZ.dll`` file. ``libSystem`` Binaries link against ``libSystem.B.dylib``, which is the mega library backing a lot of systems-level functionality in macOS. (Version 5 or above only.) run_tests The path to a Python script to run the test harness for this distribution. (Version 5 or above only.) build_info A map describing build configuration and artifacts for this distribution. See the ``build_info Data`` section below. licenses Array of strings containing the license shortname identifiers from the SPDX license list (https://spdx.org/licenses/) for the Python distribution. (Version 2 or above only.) license_path Path to a text file containing the license for this Python distribution. (Version 2 or above only.) tcl_library_path Relative path to location of tcl library files. The path should be a directory tree containing tcl files to support the tkinter extension. This will include a subset of the library files provided by the tcl, tk, and tix packages. This points to the root directory containing tcl resources. Actual tcl resources are in sub-directories underneath, as identified by ``tcl_library_paths``. (Version 3 or above only.) tcl_library_paths Array of relative paths holding tcl library files relative to ``tcl_library_path``. Because ``tcl_library_path`` can be shared with other resources (e.g. on UNIX the path is typically ``install/lib``, which holds system libraries as well), distributions may advertise the list of directories under ``tcl_library_path`` actually containing tcl resources. (Version 5 or above only.) build_info Data --------------- The ``build_info`` key in the ``PYTHON.json`` file describes build artifacts in the Python distribution. The primary goal of the data is to give downstream distribution consumers enough details to integrate build artifacts into their own build systems. This includes the ability to produce a Python binary with a custom set of built-in extension modules. This map has the following keys: core A map describing the core Python distribution (essentially `libpython`). objs An array of paths to object files constituting the Python core distribution. Core object files are typically object files that are linked together to create libpython. links An array of linking requirement maps. (See below for data format.) shared_lib Path to a shared library representing `libpython`. May not be defined. (Version 4 or above only.) static_lib Path to a static library representing `libpython`. May not be defined. (Version 4 or above only.) inittab_object Path to object file defining ``_PyImport_Inittab``, which defines built-in extension modules. (Version 5 or above only.) inittab_source Path to source code file that defines ``_PyImport_Inittab``. On CPython, this will point to a ``config.c`` file. (Version 5 or above only.) inittab_cflags Array of strings constituting compiler flags to use when compiling ``inittab_source``. (Version 5 or above only.) extensions A map of extension names to an array of maps describing candidate extensions. Extensions are non-core/non-essential parts of the Python distribution that are frequently built as standalone entities. Names in this map denote the name of the extension module. Values are arrays of maps. Each map represents a potential candidate providing the extension. There is frequently only a single extension candidate. Multiple candidates can occur if there are e.g. varying libraries an extension can be linked against to supply underlying functionality. Each map has the following keys: in_core Boolean indicating if this extension is defined by the core distribution. If true, object files should be in the ``['core']['objs']`` array, not the ``objs`` array in this map. Downstream consumers should key off this value to determine how to assemble this extension's code into a new distribution. This field was introduced to support Windows, where CPython's Visual Studio project files define various extensions as part of the project providing libpython. This is in contrast to make-based builds, where the ``Modules/Setup.*`` files treat each extension as separate entities. init_fn The name of the extension module initialization function for this extension. The string value may be ``NULL``, which may need special handling by consumers. licenses Array of strings containing the license shortname identifiers from the SPDX license list (https://spdx.org/licenses/). If this field is missing, licenses are unknown. Empty array denotes no known licenses. The license applies to additional libraries needed by this extension, not the extension itself, as extensions should be licensed the same as the Python distribution. (Version 2 or above only.) license_path Paths to text files containing the licenses for this extension. (Version 2 or above only.) license_public_domain Bool indicating that the license for the extension is in the public domain. There is no SPDX identifier for public domain. And we want to be explicit about something being in the public domain because of the legal implications. (Version 2 or above only.) links An array of linking requirement maps. (See below for data format.) objs An array of paths to object files constituting this extension module. required Boolean indicating if this extension is required to initialize the Python interpreter. shared_lib The path to a shared library defining this extension module. May not be defined. (Version 4 or above only.) static_lib The path to a static library defining this extension module. May not be defined. variant String describing this extension variant. Downstream consumers can key off this value to choose an appropriate extension variant when there are multiple options. object_file_format Denotes the data format for object files. Can be one of the following values. ``elf`` Standard object file format for Linux. ``llvm-bitcode:N`` Files are LLVM bitcode produced with LLVM version ``N``. e.g. ``llvm-bitcode:10.0.0``. This variant is typically seen for builds using LTO. ``coff`` Standard object file format for Windows. ``mach-o`` Standard object file format for macOS. (Version 5 or newer only.) Each entry in a ``links`` array is a map with the following keys: name Name of the library being linked against. path_static Path to the static version of this library, if available in the distribution. path_dynamic Path to the dynamic version of this library, if available in the distribution. framework Denotes that the link target is a macOS framework. system Denotes that the link target is a system library. System libraries are typically passed into the linker by name only and found using default library search paths. Install Only Archive ==================== At release time, this project produces tar files containing just the Python installation, without the ``PYTHON.json`` or build files from the full ``.tar.zst`` archives. These are referred to as *install only* archives. An *install only* archive is created by taking a ``.tar.zst`` and rewriting ``python/install/*`` to ``python/*``. All files not under ``python/install/*`` are not carried forward to the *install only* archive. The fastest available build for a given target is used for the *install only* archive. Builds are generally preferred in the following order: ``pgo+lto``, ``pgo``, ``lto``, ``noopt``. For maximum compatibility, gzipped compressed versions of the *install only* archives are made available.