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 inC:cygwin
(although it does not need to be included inPATH
). Current Python source packages includeprepare_libffi.bat
in thePCbuild
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 onPATH
.- 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.
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 calledbuild
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 calledsysroot-
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 isTrue
.
- 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 bename-version[.extension]
where the optionalextension
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 theSIP
component plugin.
- target_sitepackages_dir¶
The pathname of the target Python
site-packages
directory. This is only implemented by thePython
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 beNone
. In this case the component must determine the version number and set theversion
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.
- 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]
whereM
is an integer major version number,m
is an optional integer minor version number,p
is an optional integer patch version number andsuffix
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.