Building a System Root Directory

pyqtdeploy-sysroot is used to create a target-specific system root directory (sysroot) containing any components required by the application.

pyqtdeploy-sysroot is actually a wrapper around a number of component plugins. A plugin, written in Python, is responsible for installing the individual parts that make up a component. A part may be a Python package, an extension module or a supporting library.

A sysroot is defined by a TOML specification file. This contains a section for each component to install. The key/value options of a section determine how the component is configured. Component sections may have target-specific sub-sections so that they can be configured on a target by target basis.

The components are installed in the correct order irrespective of where they appear in the specification file.

A component will only be installed in a sysroot if it hasn’t already been done. However if the installed version is different then all components will be re-installed. This is done because some components take a long time to install (building Qt from source being the obvious example) making it very inconvenient when debugging the installation of a later component.

An API is provided to allow you to develop your own component plugins. If you develop a plugin for a commonly used component then please consider contributing it so that it can be included in a future release of pyqtdeploy. Defining a component in this way is described in Defining a Component Using a Plugin.

Many applications will use third-party packages packaged as wheels and installed from PyPI. Rather than require you to write a component plugin in Python for these, pyqtdeploy provides the wheel plugin which takes the necessary information about the package from the sysroot specification file. Defining a component in this way is described in Defining a Component Using the Sysroot Specification File.

Standard Component Plugins

The following component plugins are included as standard with pyqtdeploy.

libffi

This provides the libffi library as a DLL for Windows. On macOS and Linux it provides access to the OS supplied library. It is currently not supported on other target architectures. It is required by the Python ctypes module. In order to build it on Windows Cygwin must be installed in C:cygwin (although it does not need to be included in PATH). Current Python source packages include prepare_libffi.bat in the PCbuild directory which will can be run to install an appropriate version of Cygwin.

OpenSSL

This provides the OpenSSL libraries for v1.1.0 and later on Android (as a shared library), Linux (using the OS supplied library), macOS (as a static library) and Windows (as a static library). When building from source it requires perl to be installed on PATH.

PyQt

This provides a static version of the PyQt5 extension modules for all target architectures.

PyQt3D

This provides a static version of the PyQt3D extension modules for all target architectures.

PyQtChart

This provides a static version of the PyQtChart extension module for all target architectures.

PyQtDataVisualization

This provides a static version of the PyQtDataVisualization extension module for all target architectures.

PyQtNetworkAuth

This provides a static version of the PyQtNetworkAuth extension module for all target architectures.

PyQtPurchasing

This provides a static version of the PyQtPurchasing extension module for all target architectures.

PyQtWebEngine

This provides a static version of the PyQtWebEngine extension module for all target architectures.

Python

This will provide Python from source, or use an existing installation, for both the host and target architectures. Building the host version from source is not supported on Windows. Installing the host version from an existing installation is not supported on Android or iOS. The target version of the Python library and extension modules built from source will be built statically. Installing the target version from an existing installation is only supported on Windows.

QScintilla

This provides a static version of the QScintilla library and Python extension module for all target architectures.

Qt

This will provide a static version of Qt5 from source (but not for the Android and iOS targets). It will use an existing installation created by the standard Qt installer.

SIP

This provides a static version of the sip extension module for all target architectures.

zlib

This provides a static version of the zlib library for all target architectures. It can also use an OS supplied library for all targets except Windows.

Creating a Sysroot Specification File

The following specification file contains a section for each of the standard component plugins. (You can also download a copy of the file from here). Dummy values have been used for all required configuration options.

# A skeleton sysroot specification file.


[libffi]
version = "0.0.0"

[OpenSSL]
version = "0.0.0"

[Python]
version = "0.0.0"

[PyQt]
version = "0.0.0"
installed_modules = []

[PyQt3D]
version = "0.0.0"

[PyQtChart]
version = "0.0.0"

[PyQtDataVisualization]
version = "0.0.0"

[PyQtNetworkAuth]
version = "0.0.0"

[PyQtPurchasing]
version = "0.0.0"

[PyQtWebEngine]
version = "0.0.0"

[QScintilla]
version = "0.0.0"

[Qt]
version = "0.0.0"

[SIP]
version = "0.0.0"
module_name = ""

[zlib]
version = "0.0.0"

Using this file, run the following command:

pyqtdeploy-sysroot --options sysroot.toml

You will then see a description of each component’s configuration options, the type of value expected and whether or not a value is required. You can then add options to the appropriate sections to meet your requirements.

If your application does not require all of the standard components then simply remove the corresponding sections from the specification file. If your application requires additional components then you need to create appropriate component plugins and add corresponding sections to the specification file.

At any time you can verify your specification file. This will check that all required options have a value and that all components have supported versions that are mutually compatible. It will also warn you if you have specified versions that are untested (but should work). To do this run:

pyqtdeploy-sysroot --verify sysroot.toml

To build a native sysroot (i.e. for the host architecture) from a fully configured specification file, run:

pyqtdeploy-sysroot sysroot.toml

The pyqt-demo Sysroot

In this section we walk through the sysroot specification file for pyqt-demo, component by component.

OpenSSL

[OpenSSL]
version = "1.1.1m"
disabled_targets = ["ios"]

[OpenSSL.linux]
version = ""
install_from_source = false

On iOS we choose to not support SSL from Python and use Qt’s SSL support instead (which will use Apple’s Secure Transport).

On Linux we will use the OS supplied OpenSSL libraries and make no assumption about what version might be installed.

Python

[Python]
version = "3.10.4"
install_host_from_source = true

[Python.win]
install_host_from_source = false

The Python component plugin handles installation for both host and target architectures. For the host we choose to install from source except on Windows where the registry is searched for the location of an existing installation. For all target architecures we choose to build Python from source.

pyqt-demo is a very simple application that does not need to dynamically load extension modules. If this was needed then the dynamic_loading option would be set to true.

PyQt

[PyQt]
version = "5.15.6"

[PyQt.android]
disabled_features = ["PyQt_Desktop_OpenGL", "PyQt_Printer"]
installed_modules = ["QtCore", "QtGui", "QtNetwork", "QtWidgets",
        "QtAndroidExtras"]

[PyQt.ios]
disabled_features = ["PyQt_Desktop_OpenGL", "PyQt_MacOSXOnly",
        "PyQt_MacCocoaViewContainer", "PyQt_Printer", "PyQt_Process",
        "PyQt_NotBootstrapped"]
installed_modules = ["QtCore", "QtGui", "QtNetwork", "QtWidgets",
        "QtMacExtras"]

[PyQt.linux]
installed_modules = ["QtCore", "QtGui", "QtNetwork", "QtWidgets",
        "QtX11Extras"]

[PyQt.macos]
installed_modules = ["QtCore", "QtGui", "QtNetwork", "QtWidgets",
        "QtMacExtras"]

[PyQt.win]
disabled_features = ["PyQt_Desktop_OpenGL"]
installed_modules = ["QtCore", "QtGui", "QtNetwork", "QtWidgets",
        "QtWinExtras"]

The two options used to tailor the build of PyQt are disabled_features and installed_modules.

Unfortunately the list of features that can be disabled is not properly documented and relate to how Qt is configured. However how disabled_features is set in the above will be appropriate for most cases.

The installed_modules option is used to specify the names of the individual PyQt extension modules to be installed. We choose to build only those extension modules needed by pyqt-demo.

PyQt3D

[PyQt3D]
version = "5.15.5"

It is only necessary to specifiy the version to install.

PyQtChart

[PyQtChart]
version = "5.15.5"

It is only necessary to specifiy the version to install.

PyQtDataVisualization

[PyQtDataVisualization]
version = "5.15.5"

It is only necessary to specifiy the version to install.

PyQtNetworkAuth

[PyQtNetworkAuth]
version = "5.15.5"

It is only necessary to specifiy the version to install.

PyQtPurchasing

[PyQtPurchasing]
version = "5.15.5"

It is only necessary to specifiy the version to install.

QScintilla

[QScintilla]
version = "2.13.2"

It is only necessary to specifiy the version to install.

Qt

[Qt]
version = "5.15.2"
edition = "opensource"
configure_options = ["-opengl", "desktop", "-no-dbus", "-qt-pcre"]
skip = ["qtactiveqt", "qtconnectivity", "qtdoc", "qtgamepad", "qtlocation",
        "qtmultimedia", "qtnetworkauth", "qtquickcontrols",
        "qtquickcontrols2", "qtremoteobjects", "qtscript", "qtscxml",
        "qtsensors", "qtserialbus", "qtserialport", "qtspeech", "qtsvg",
        "qttools", "qttranslations", "qtwayland", "qtwebchannel",
        "qtwebengine", "qtwebsockets", "qtwebview", "qtxmlpatterns"]

[Qt.android]
install_from_source = false
ssl = "openssl-linked"

[Qt.ios]
install_from_source = false
ssl = "securetransport"

[Qt.linux]
ssl = "openssl-runtime"

[Qt.macos]
ssl = "openssl-linked"

[Qt.win]
ssl = "openssl-linked"
static_msvc_runtime = true

We have chosen to install Qt from source except for Android and iOS where we will use an existing installation. In the context of the demo this is defined by the --qmake option of the build-demo.py script.

We use the configure_options and skip options to tailor the Qt build in order to reduce the time taken to do the build.

The ssl option specifies how Qt’s SSL support is to be implemented.

On Android we have chosen to link against the shared OpenSSL libraries installed by the OpenSSL component plugin which are bundled automaticallly with the application executable.

On iOS Qt is dynamically linked to the Secure Transport libraries.

On Linux we have chosen to dynamically load the OS supplied OpenSSL libraries at runtime.

On macOS and Windows we have chosen to link against the static OpenSSL libraries installed by the OpenSSL component plugin.

Finally we have specified that (on Windows) we will link to static versions of the MSVC runtime libraries.

SIP

[SIP]
abi_major_version = 12
module_name = "PyQt5.sip"

Note that the version number of SIP does not need to be specified. A suitable versions of PyQt-builder must be installed for the same Python installation being used to run pyqtdeploy.

zlib

[zlib]
install_from_source = false

[zlib.win]
version = "1.2.12"
install_from_source = true
static_msvc_runtime = true

On all targets, except for Windows, we choose to use the zlib library provided by the OS.

On Windows we choose to build from the latest version of the source and link to static versions of the MSVC runtime libraries.

The Command Line

The full set of command line options is:

-h, --help

This will display a summary of the command line options.

-V, --version

This specifies that the version number should be displayed on stdout. The program will then terminate.

--build-dir DIR

New in version 3.3.0.

DIR is the name of the temporary build directory used to build each component. By default a directory called build in the target-specific sysroot directory is used.

--component COMPONENT

COMPONENT is the name of the component that will be installed. It may be used more than once to install multiple components. If the option is not specified then all components specified in the sysroot specification file will be installed.

--force

This causes all components to be installed even if components with the required versions have already been installed.

--jobs NUMBER

New in version 3.3.0.

This specifies the number of make jobs that will be run in parallel. It only has an affect on Linux and macOS hosts.

--no-clean

A temporary build directory (by default called build in the sysroot) is created in order to build the required components. Normally this is removed automatically after all components have been built. Specifying this option leaves the build directory in place to make debugging component plugins easier.

--options

This causes the configurable options of each component specified in the sysroot specification file to be displayed on stdout. The program will then terminate.

--python EXECUTABLE

EXECUTABLE is the full path name of the host Python interpreter. It overrides any value provided by the sysroot but the version must be compatible with that specified in the sysroot specification file.

--qmake EXECUTABLE

EXECUTABLE is the full path name of the host qmake. It overrides any value provided by the sysroot but the version must be compatible with that specified in the sysroot specification file.

--source-dir DIR

DIR is the name of a directory containing any local copies of source archives used to install the components specified in the sysroot specification file. It may be specified any number of times and each directory will be searched in turn. If a local copy cannot be found then the component plugin will attempt to download it.

--sysroots-dir DIR

DIR is the name of the directory where the target-specific sysroot directory will be created. A sysroot directory will be called sysroot- followed by a target-specific suffix. If all components are to be re-installed then any existing sysroot will first be removed and re-created.

--target TARGET

TARGET is the target architecture. By default the host architecture is used. On Windows the default is determined by the target architecture of the currently configured compiler.

--quiet

This specifies that progress messages should be disabled.

--verbose

This specifies that additional progress messages should be enabled.

specification

specification is the name of the sysroot specification file that defines each component to be included in the sysroot and how each is to be configured.

Defining a Component Using the Sysroot Specification File

New in version 3.2.0.

As an example we will define a component for the certifi project on PyPI. It contains a small number of .py files and a data file, and only imports modules from the Python standard library.

A component defined in the sysroot specification file makes use of the wheel component plugin that is included with pyqtdeploy.

The following is the complete component definition:

[certifi]
plugin = "wheel"
wheel = "certifi-2021.10.8-py2.py3-none-any.whl"
dependencies = ["Python:importlib.resources", "Python:os"]
exclusions = ["__main__.py"]

plugin specifies that wheel is the component plugin to use. For components that have a dedicated plugin it is not normally required as it defaults to the name of the component.

wheel specifies the name of the wheel file that will be installed in the sysroot.

dependencies specifies a list of packages that the component depends on, i.e. packages that are imported by the component. A dependency is specified as a component name and package name separated by :. In this case certifi imports importlib.resources and os from the Python standard library.

exclusions specifies a list of files in the wheel that should not be included as part of the deployed application. In this case the __main__.py file is not used and therefore excluded.

Note

certifi reads it’s data file (cacert.pem) using Python’s resources mechanism (i.e. importlib.resources). This means that it can read the file even though it will be embedded in the executable created by pyqtdeploy.

Defining a Component Using a Plugin

While using the sysroot specification file to define a component is convenient in simple cases, it is often better to define a component using a component plugin. For example:

  • you may need to check the component’s version number to determine its exact dependencies and what it provides

  • you may need to check the version numbers of any components on which it depends

  • you may need to check that other requirements have been met, such as the correct version of an SDK.

Using a component plugin also makes it easier to build up a library of plugins to be used in multiple projects.

A component plugin is a Python module that defines a sub-class of pyqtdeploy.Component. Normally the name of the module is the name used in the sysroot specification file (although plugin can be used to change this). It doesn’t matter what the name of the sub-class is.

The following is a complete implementation of a component plugin for the certifi project on PyPI.

from pyqtdeploy import Component, PythonPackage

class certifiComponent(Component):

    # The list of components that should be installed before this one.
    preinstalls = ['Python']

    # The dictionary of parts provided by the component keyed by the name
    # of the part.  In this case there is a single part which is a Python
    # package (ie. a directory containing a __init__.py file).
    provides = {
        'certifi': PythonPackage(
                deps=['Python:importlib.resources', 'Python:os'],
                exclusions='__main__.py')
    }

    def get_archive_name(self):
        """ Get the version dependent name of the wheel. """

        return 'certifi-{}-py2.py3-none-any.whl'.format(self.version)

    def get_archive_urls(self):
        """ Get the list of URLs where the wheel might be downloaded from.
        """

        # Return the PyPI URLs for the project.
        return self.get_pypi_urls('certifi')

    def install(self):
        """ Install the component. """

        # Unpack the wheel into the target Python installation's
        # site-packages directory.
        self.unpack_wheel(self.get_archive())

Hopefully the comments in the code are self explainatory.

The complete would be used as follows:

[certifi]
version = "2021.10.8"

Component plugins (other than those bundled with pyqtdeploy) are expected to be found in the directory containing the sysroot specification file.

The following is the complete API available to a plugin.

class pyqtdeploy.Component

This is the base class of all component plugins.

android_abi

The Android architecture-specific ABI being used.

android_api

The integer Android API level being used.

android_ndk_root

The path of the root of the Android NDK.

android_ndk_sysroot

The path of the Android NDK’s sysroot directory.

android_ndk_version

The the version number of the Android NDK.

android_sdk_version

The version number of the Android SDK.

android_toolchain_bin

The path of the Android toolchain’s bin directory.

android_toolchain_cc

The name of the Android toolchain’s C compiler.

android_toolchain_prefix

The name of the Android toolchain’s prefix.

apple_sdk

The Apple SDK being used.

apple_sdk_version

The version number of the Apple SDK.

building_for_target

This is set to True by the component plugin to configure building (i.e. compiling and linking) for the target (rather than the host) architecture. The default value is True.

copy_dir(src, dst, ignore=None)

A directory is copied, optionally excluding file and sub-directories that match a number of glob patterns. If the destination directory already exists then it is first removed. Any errors are handled automatically.

Parameters
  • src (str) – the name of the source directory.

  • dst (str) – the name of the destination directory.

  • ignore (list[str]) – an optional sequence of glob patterns that specify files and sub-directories that should be ignored.

copy_file(src, dst, macros=None)

A file is copied while expanding and optional dict of macros. Any errors are handled automatically.

Parameters
  • src (str) – the name of the source file.

  • dst (str) – the name of the destination file.

  • macros (dict) – the dict of name/value pairs.

create_dir(name, empty=False)

A new directory is created if it does not already exist. If it does already exist then it is optionally emptied. Any errors are handled automatically.

Parameters
  • name (str) – the name of the directory.

  • empty (bool) – True if an existing directory should be emptied.

create_file(name)

A new text file is created and its file object returned. Any errors are handled automatically.

Parameters

name (str) – the name of the file.

Returns

the file object of the created file.

delete_dir(name)

A directory and any contents are deleted. Any errors are handled automatically.

Parameters

name (str) – the name of the directory.

error(message, detail='')

An error message is displayed to the user and the program immediately terminates.

Parameters
  • message (str) – the message.

  • detail (str) – additional detail displayed if the --verbose option was specified.

find_exe(name, required=True)

The absolute path name of an executable located on PATH is returned.

Parameters
  • name (str) – the generic executable name.

  • required (bool) – True if the executable is required and it is an error if it could not be found.

Returns

the absolute path name of the executable.

get_archive(name):

The pathname of a local copy of the component’s source archive is returned. The directories specified by the --source-dir option are searched first. If the archive is not found then it is downloaded if the component supports it.

Returns

the pathname of the archive.

get_archive_name():

This must be re-implemented to return the version-specific name of the component’s source archive.

Returns

the name of the archive.

get_archive_urls():

This is re-implemented to return a sequence of URLs (excluding the source archive name) from which the component’s source archive may be downloaded from.

Returns

the sequence of URLs.

get_component(name, required=True)

The Component instance for a component is returned.

Parameters
  • name (str) – the name of the component.

  • required (bool) – True if the component is required and it is an error if it was not specified.

Returns

the component instance.

get_file(name)

The absolute path name of a file or directory in a directory specified by a --source-dir option is returned.

Parameters

name (str) – the name of the file or directory.

Returns

the absolute path name of the file or directory or None if it wasn’t found.

get_options()

A sequence of ComponentOption instances describing the component’s configurable options is returned.

Returns

the sequence of option instances.

get_pypi_urls(pypi_project):

This can be called from a re-implementation of get_archive_urls() to return a sequence of URLs (excluding the source archive name) from which the component’s source archive may be downloaded from a PyPI project.

Parameters

pypi_project (str) – the name of the PyPI project.

Returns

the sequence of URLs.

get_python_install_path(major, minor)

The name of the directory containing the root of a Python installation on Windows is returned. It must only be called by a Windows host.

Parameters
  • major (int) – the major version number.

  • minor (int) – the major version number.

Returns

the absolute path of the installation directory.

get_version_from_file(identifier, filename)

A file is read and a (stripped) line containing an identifier (typically a pre-processor macro defining a version number) is returned. it is an error if the identifier could not be found.

Parameters
  • identifer (str) – the identifier to find.

  • filename (str) – the name of the file to read.

Returns

the stripped line containing the identifier.

get_versioned_file(package)

New in version 3.3.0.

A resource package is searched for a file with a version number embedded in the name. The name of the most appropriate file for the version of the component is returned or None if there wasn’t one. The format of the name must be name-version[.extension] where the optional extension must be one of .py, .h, .c or .cpp.

Parameters

package (module) – the package to search.

Returns

the name of the file or None.

host_dir

The name of the directory where components built for the host architecture should be installed.

host_exe(name)

A generic executable name is converted to a host-specific version.

Parameters

name (str) – the generic name.

Returns

the host-specific name.

host_make

The name of the host make executable.

host_platform_name

The name of the host platform.

host_python

The name of the host python executable. This is only implemented by the Python component plugin.

host_qmake

The name of the host qmake executable. This is only implemented by the Qt component plugin.

host_sip

The name of the host sip executable. This is only implemented by the SIP component plugin.

abstract install()

This must be re-implemented to install the component.

must_install_from_source

Deprecated since version 3.2.0: Use option_install_from_source instead.

This is set by the component if it must be installed from a source archive.

open_file(name)

An existing text file is opened and its file object returned. Any errors are handled automatically.

Parameters

name (str) – the name of the file.

Returns

the file object of the opened file.

option_install_from_source

New in version 3.2.0.

This is set by the component if it supports the install_from_source component option.

static parse_version_number(version_nr)

A version number is converted to a VersionNumber instance. It may be a string, an encoded integer or a tuple.

Parameters

name (str, int, or tuple) – the version number to parse.

Returns

the version number.

patch_file(name, patcher)

Patch a file.

Parameters
  • name (str) – the name of the file to patch

  • patcher (callable) – invoked for each line of the file and passed the line and a file object to which the (possibly) modified line should be written to.

preinstalls

The list of components that this component is dependent on.

progress(message)

A progress message is displayed to the user. It will be suppressed if the --quiet option was specified.

Parameters

message (str) – the message.

provides

The dict of parts, keyed by the name of the part, provided by this component.

run(*args, capture=False)

An external command is run. The command’s stdout can be optionally captured.

Parameters
  • *args – the name of the command and its arguments.

  • capture (bool) – True if the command’s stdout should be captured and returned.

Returns

the stdout of the command if requested, otherwise None.

sdk_configure(platform_name)

This should be implemented to perform any SDK-specific configuration prior to installing the component.

Parameters

platform_name (str) – the target platform name.

sdk_deconfigure(platform_name)

This should be implemented to remove any SDK-specific configuration after to installing the component.

Parameters

platform_name (str) – the target platform name.

sysroot_dir

The full pathname of the system root directory.

target_arch_name

The name of the target architecture.

target_include_dir

The name of the directory where header files built for the target architecture should be installed.

target_lib_dir

The name of the directory where libraries built for the target architecture should be installed.

target_platform_name

The name of the target platform.

target_py_include_dir

The pathname of the directory containing the target Python header files. This is only implemented by the Python component plugin.

target_py_lib

The name of the target Python library. This is only implemented by the Python component plugin.

target_sip_dir

The pathname of the directory containing the target .sip files. This is only implemented by the SIP component plugin.

target_sitepackages_dir

The pathname of the target Python site-packages directory. This is only implemented by the Python component plugin.

target_src_dir

The name of the directory where source files can be found. Note that these are sources left by components for the use of other components and not the sources used to build a component.

unpack_archive(archive, chdir=True)

A source archive is unpacked in the current directory and the name of the archive directory (not its pathname) is returned.

Parameters
  • archive (str) – the pathname of the source archive.

  • chdir (bool) – True if the current directory is changed to be the archive directory.

Returns

the name of the archive directory.

unpack_wheel(wheel_path)

New in version 3.2.0.

A wheel is unpacked in the target Python installation’s site-packages directory.

Parameters

wheel_path (str) – the pathname of the wheel file.

unsupported(detail=None)

Issue an error message that the version of the component is unsupported.

Parameters

detail (str) – additional detail to append to the message.

untested()

Issue a warning message that the version of the component is untested.

verify()

This can be re-implemented to verify the component. A component will always be verified even if it does not get installed. The plugin should check that everything is available (e.g. other components, external tools) using the specified versions for a successful installation.

New in version 3.2.0.

If the version number is optional for the component and it has been omitted then the version attribute will be None. In this case the component must determine the version number and set the version attribute accordingly.

verbose(message)

A verbose progress message is displayed to the user. It will be suppressed unless the --verbose option was specified.

Parameters

message (str) – the message.

verbose_enabled

This is set if the --verbose option was specified.

version_is_optional

New in version 3.2.0.

This is set by the component if the version number specified in the sysroot specification file is optional.

warning(message)

A warning progress message is displayed to the user.

Parameters

message (str) – the message.

class pyqtdeploy.ComponentOption(name, type=str, required=False, default=None, values=None, help='')

This class implements an option used to configure the component. An option can be specified as an attribute of the component’s object in the sysroot specification file. An instance of the component plugin will contain an attribute for each option whose value is that specified in the sysroot specification file (or an appropriate default if it was omitted).

Parameters
  • name (str) – the name of the option.

  • type (bool, int, list or str) – the type of a value of the option.

  • required (bool) – True if a value for the option is required.

  • default – the default value of the option.

  • values – the possible values of the option.

  • help (str) – the help text displayed by the --options option of pyqtdeploy-sysroot.

class pyqtdeploy.VersionNumber

This class encapsulates a version number in the form M[.m[.p]][suffix] where M is an integer major version number, m is an optional integer minor version number, p is an optional integer patch version number and suffix is an optional string suffix.

Instances may be compared with other instances, integers or tuples to determine equality or relative chronology. An integer is interpreted as a major version number. A tuple may have between one and four elements and the number of elements determines the precision of the comparison. For example, if a 2-tuple is specified then only the major and minor version numbers are considered and the patch version numbers and suffixes are ignored.

__str__()

Convert the version number to a user friendly representation.

Returns

the version number as a string.

major

The major version number.

minor

The minor version number.

patch

The patch version number.

suffix

The suffix.

Defining Component Parts

The following classes are used to define the different types of part that a component can provide.

A part is provided by a range of versions of the component. The optional min_version is the minimum version of the component that provides the part. The optional max_version is the maximum version of the component that provides the part. The optional version can be used to specify an exact version of the component that provides the part and is the equivalent of specifying the same value for both min_version and max_version. A version can be specified as either an integer major version number, a 2-tuple of major and minor version numbers or a 3-tuple of major, minor and patch version numbers.

Several attributes of different parts are described as sequences of scoped values. A scoped value is a scope and a value separated by #. A scope defines one or more targets. If the current target is defined by the scope then the value is used, otherwise it is ignored. A scope may be one or more architecture or platform names separated by | meaning that the scope defines all the the specified architectures or platforms. An individual name may be preceded by ! which excludes the name from the scope. For example ios|macos defines the value for the iOS and macOS platforms and !win-32 defines the value for all targets except for 32-bit Windows.

Some parts may be dependent on other parts, possibly parts provided by different components. A dependency may be specified as a component name and a part name separated by :. If the component name is omitted then the current component is assumed.

class pyqtdeploy.ComponentLibrary(min_version=None, version=None, max_version=None, target='', defines=None, libs=None, includepath=None, bundle_shared_libs=False)

This class encapsulates a library that is usually a dependency of an extension module.

Parameters
  • min_version (int, 2-tuple or 3-tuple) – the minimum version of the component providing the part.

  • version (int, 2-tuple or 3-tuple) – the exact version of the component providing the part.

  • max_version (int, 2-tuple or 3-tuple) – the maximum version of the component providing the part.

  • target (str) – the target platform for which the part is provided.

  • defines (sequence) – the scoped pre-processor macros to be added to the DEFINES qmake variable.

  • libs (sequence) – the scoped library names to be added to the LIBS qmake variable.

  • includepath (sequence) – the scoped directory names to be added to the INCLUDEPATH qmake variable.

  • bundle_shared_libs (bool) – True if the libraries are shared and need to be bundled with the application. Current this only applies to Android and Windows targets. In the case of Windows the component’s DLLs are copied to the same directory as the final executable so that it will run in situ, however it is up to the developer to ensure that the DLLs are included with the executable when the application is actually deployed.

class pyqtdeploy.DataFile(name, min_version=None, version=None, max_version=None, target='')

This class encapsulates a data file.

Parameters
  • name (str) – the name of the file.

  • min_version (int, 2-tuple or 3-tuple) – the minimum version of the component providing the part.

  • version (int, 2-tuple or 3-tuple) – the exact version of the component providing the part.

  • max_version (int, 2-tuple or 3-tuple) – the maximum version of the component providing the part.

  • target (str) – the target platform for which the part is provided.

class pyqtdeploy.ExtensionModule(min_version=None, version=None, max_version=None, target='', min_android_api=None, deps=(), defines=None, libs=None, includepath=None, source=None, qmake_config=None, qmake_cpp11=False, qmake_qt=None)

This class encapsulates an extension module.

Parameters
  • min_version (int, 2-tuple or 3-tuple) – the minimum version of the component providing the part.

  • version (int, 2-tuple or 3-tuple) – the exact version of the component providing the part.

  • max_version (int, 2-tuple or 3-tuple) – the maximum version of the component providing the part.

  • target (str) – the target platform for which the part is provided.

  • min_android_api (int) – the minimum Android API level required.

  • deps (sequence) – the scoped names of other parts that this part is dependent on.

  • defines (sequence) – the scoped pre-processor macros to be added to the DEFINES qmake variable.

  • libs (sequence) – the scoped library names to be added to the LIBS qmake variable.

  • includepath (sequence) – the scoped directory names to be added to the INCLUDEPATH qmake variable.

  • source (str or sequence) – the name of the source file(s) of the extension module.

  • qmake_config (str or sequence) – the value(s) to be added to the CONFIG qmake variable.

  • qmake_cpp11 (bool) – True if the extension module requires support for C++11.

  • qmake_qt (str or sequence) – the value(s) to be added to the QT qmake variable.

class pyqtdeploy.PythonModule(min_version=None, version=None, max_version=None, target='', min_android_api=None, deps=())

This class encapsulates a Python module (i.e. a single .py file).

Parameters
  • min_version (int, 2-tuple or 3-tuple) – the minimum version of the component providing the part.

  • version (int, 2-tuple or 3-tuple) – the exact version of the component providing the part.

  • max_version (int, 2-tuple or 3-tuple) – the maximum version of the component providing the part.

  • target (str) – the target platform for which the part is provided.

  • min_android_api (int) – the minimum Android API level required.

  • deps (sequence) – the scoped names of other parts that this part is dependent on.

class pyqtdeploy.PythonPackage(min_version=None, version=None, max_version=None, target='', min_android_api=None, deps=(), exclusions=())

This class encapsulates a Python package (i.e. a directory containing an __init__.py file and other .py files).

Parameters
  • min_version (int, 2-tuple or 3-tuple) – the minimum version of the component providing the part.

  • version (int, 2-tuple or 3-tuple) – the exact version of the component providing the part.

  • max_version (int, 2-tuple or 3-tuple) – the maximum version of the component providing the part.

  • target (str) – the target platform for which the part is provided.

  • min_android_api (int) – the minimum Android API level required.

  • deps (sequence) – the scoped names of other parts that this part is dependent on.

  • exclusions (sequence) – the names of any files or directories, relative to the package, that should be excluded.