Command Line Tools
The tools can also be invoked using the -m
command line option of the
Python interpreter. For example, the following two command lines are
equivalent:
sip-build -h
python -m sipbuild.tools.build -h
Note that, for the build tools, the command line options described in this
section are the standard options. Any of these options could be removed, or
new options added, by build system extensions including project-specific
project.py
files.
sip-build
sip-build builds a project but does not install it. This is useful when developing a set of bindings.
The syntax of the sip-build command line is:
sip-build [options]
The full set of command line options is:
- -h, --help
Display a help message.
- -V, --version
Display the SIP version number.
- --deprecations-are-errors
The use of any deprecated feature is handled as an error rather than a warning.
- --quiet
All progress messages are disabled.
- --verbose
Verbose progress messages are enabled.
- --api-dir DIR
A QScintilla
.api
file is created inDIR
.
- --build-dir DIR
DIR
is created as a build directory in which all generated files will be created. The build directory is not removed after the build has been completed. The default value isbuild
.
- --concatenate N
The generated code is split into
N
files. By default one file is generated for each C structure or C++ class. Specifying a low value ofN
can significantly speed up the build of large projects.
- --disable NAME
The
NAME
bindings are disabled and will not be built. This option may be specified multiple times. It is only available if the project contains multiple sets of bindings.
- --disabled-feature TAG
The
TAG
feature tag is disabled. This option may be specified multiple times.
- --enable NAME
The
NAME
bindings are enabled and will be built. Any associated configuration tests that would normally be run to determine if the bindings should be built are suppressed. This option may be specified multiple times. It is only available if the project contains multiple sets of bindings.
- --debug
A build with debugging symbols is performed.
- --no-compile
The compilation of the generated code is disabled.
- --no-docstrings
The generation of docstrings that describe the signature of all functions, methods and constructors is disabled.
- --no-version-info
No reference the SIP version number is included in any generated code.
- --pep484-pyi
The generation of Python type hints stub files is enabled. These files contain a description of a module’s API that is compliant with PEP 484.
- --protected-is-public
SIP can generate code to provide access to protected C++ functions from Python. On non-Windows platforms this code can be avoided if the
protected
keyword is redefined aspublic
during compilation. This can result in a significant reduction in the size of a generated Python module. This option enables the redefinition ofprotected
and is the default on all platforms except Windows.
- --no-protected-is-public
This option disables the redefinition of
protected
to access protected C++ functions from Python and is the default on Windows.
- --scripts-dir DIR
Any project scripts will eventually be installed in
DIR
. IfDIR
is relative then it is taken as relative to the target directory. By default the directory containing the Python interpreter is used.
- --target-dir DIR
The project will eventually be installed in
DIR
. By default it is thesite-packages
directory of the Python installation.
- --tracing
Debugging statements that trace the execution of the bindings are automatically generated. By default the statements are not generated.
sip-distinfo
sip-distinfo creates and populates a .dist-info
directory of
an installation or a wheel. It is provided for build systems that extend the
SIP build system and need to create the .dist-info
directory from an
external tool such as make.
The syntax of the sip-distinfo command line is:
sip-distinfo [options] directory
directory
is the full path name of the directory to create.
The full set of command line options is:
- -h, --help
Display a help message.
- -V, --version
Display the SIP version number.
- --console-script ENTRY-POINT
The console entry point
ENTRY-POINT
is added to the wheel. It is ignored if the--wheel-tag
option is not specified. This option may be specified multiple times.
- --generator NAME
If the
--wheel-tag
option is specified thenNAME
is written as part of theGenerator
in theWHEEL
file in the.dist-info
directory. OtherwiseNAME
is written to theINSTALLER
file. By defaultsipbuild
is written.
- --generator-version VERSION
VERSION
is written as part of theGenerator
in theWHEEL
file in the.dist-info
directory. By default the SIP version number is written.
- --gui-script ENTRY-POINT
The GUI entry point
ENTRY-POINT
is added to the wheel. It is ignored if the--wheel-tag
option is not specified. This option may be specified multiple times.
- --inventory FILE
FILE
contains a list of the relative names of the files, one per line, that comprise the installation or wheel contents. This option must be specified.
- --metadata NAME[=VALUE]
VALUE
is used instead of any value specified forNAME
in the[tool.sip.metadata]
section of thepyproject.toml
file.
- --prefix DIR
This option is provided as an aid to Linux package builders.
DIR
is used to pass the commonly used values ofDESTDIR
orINSTALL_ROOT
. If specified it should have a trailing native path separator.
- --project-root DIR
The name of the directory containing the project’s
pyproject.toml
file isDIR
. This option must be specified.
- --requires-dist EXPR
EXPR
is added to the list of prerequisites written to theMETADATA
file in the.dist-info
directory. It is normally used to specify a particular version of a package project’ssip
module. This option may be specified multiple times.
- --wheel-tag TAG
TAG
is written as theTag
in theWHEEL
file in the.dist-info
directory.
sip-install
sip-install builds and installs a project.
The syntax of the sip-install command line is:
sip-install [options]
The full set of command line options is:
- -h, --help
Display a help message.
- -V, --version
Display the SIP version number.
- --deprecations-are-errors
The use of any deprecated feature is handled as an error rather than a warning.
- --quiet
All progress messages are disabled.
- --verbose
Verbose progress messages are enabled.
- --api-dir DIR
A QScintilla
.api
file is created inDIR
.
- --build-dir DIR
DIR
is created as a build directory in which all generated files will be created. This build directory is not removed after the build has been completed. By default a temporary build directory is created which is removed after the build has been completed.
- --concatenate N
The generated code is split into
N
files. By default one file is generated for each C structure or C++ class. Specifying a low value ofN
can significantly speed up the build of large projects.
- --disable NAME
The
NAME
bindings are disabled and will not be built. This option may be specified multiple times. It is only available if the project contains multiple sets of bindings.
- --disabled-feature TAG
The
TAG
feature tag is disabled. This option may be specified multiple times.
- --enable NAME
The
NAME
bindings are enabled and will be built. Any associated configuration tests that would normally be run to determine if the bindings should be built are suppressed. This option may be specified multiple times. It is only available if the project contains multiple sets of bindings.
- --debug
A build with debugging symbols is performed.
- --no-docstrings
The generation of docstrings that describe the signature of all functions, methods and constructors is disabled.
- --no-distinfo
The creation of the
.dist-info
directory is disabled.
- --pep484-pyi
The generation of Python type hints stub files is enabled. These files contain a description of a module’s API that is compliant with PEP 484.
- --protected-is-public
SIP can generate code to provide access to protected C++ functions from Python. On non-Windows platforms this code can be avoided if the
protected
keyword is redefined aspublic
during compilation. This can result in a significant reduction in the size of a generated Python module. This option enables the redefinition ofprotected
and is the default on all platforms except Windows.
- --no-protected-is-public
This option disables the redefinition of
protected
to access protected C++ functions from Python and is the default on Windows.
- --scripts-dir DIR
Any project scripts will be installed in
DIR
. IfDIR
is relative then it is taken as relative to the target directory. By default the directory containing the Python interpreter is used.
- --target-dir DIR
The project will be installed in
DIR
. By default it is thesite-packages
directory of the Python installation.
- --tracing
Debugging statements that trace the execution of the bindings are automatically generated. By default the statements are not generated.
sip-module
sip-module builds one of more of the elements of the sip
module for a set of package projects.
The syntax of the sip-module command line is:
sip-module [options] name
name
is the fully qualified name of the sip
module (i.e. including
the package name).
The full set of command line options is:
- -h, --help
Display a help message.
- -V, --version
Display the SIP version number.
- --abi-version MAJOR[.MINOR]
The major version number of the ABI implemented by the
sip
module isMAJOR
. If a minor version number is also specified it is interpreted as a minimum minor version rather than the exact minor version to be used. By default the very latest version is used.
- --project NAME
The name of the project as it would appear on PyPI is
NAME
. By default the name is derived from the fully qualified name of thesip
module.
- --sdist
Create an sdist which can then be installed by pip or uploaded to PyPI.
pip can also be used to create a wheel from the sdist. However, for Linux wheels, auditwheel must be run for the wheel before it can be uploaded to PyPI.
- --setup-cfg FILE
FILE
is copied to the sdist assetup.cfg
instead of the default version. This allows the sdist to be customised. A number of macros may be specified in thesetup.cfg
file:@SIP_MODULE_FQ_NAME@
is replaced by the fully qualified name of thesip
module.@SIP_MODULE_PACKAGE_NAME@
is replaced by the module’s project top-level package name.@SIP_MODULE_PROJECT_NAME@
is replaced by the module’s project name as it would appear on PyPI.@SIP_MODULE_VERSION@
is replaced by the version number of the module.
- --sip-h
Create a
sip.h
header file that defines the C ABI implemented by thesip
module.
- --sip-rst
Create a
sip.rst
file that documents the Python API implemented by thesip
module.
- --target-dir DIR
Each of the module’s elements will be created in
DIR
.
sip-sdist
sip-sdist creates an sdist (a source distribution) than be uploaded to PyPI.
The syntax of the sip-sdist command line is:
sip-sdist [options]
The full set of command line options is:
- -h, --help
Display a help message.
- -V, --version
Display the SIP version number.
- --deprecations-are-errors
The use of any deprecated feature is handled as an error rather than a warning.
- --name NAME
NAME
is used instead of the PyPI project name in thepyproject.toml
file in the name of the sdist file.
sip-wheel
sip-wheel creates a wheel (a binary distribution) than be uploaded to PyPI.
The syntax of the sip-wheel command line is:
sip-wheel [options]
The full set of command line options is:
- -h, --help
Display a help message.
- -V, --version
Display the SIP version number.
- --deprecations-are-errors
The use of any deprecated feature is handled as an error rather than a warning.
- --quiet
All progress messages are disabled.
- --verbose
Verbose progress messages are enabled.
- --api-dir DIR
A QScintilla
.api
file is created inDIR
. This must be a name relative to the directory where the wheel will be installed.
- --build-dir DIR
DIR
is created as a build directory in which all generated files will be created. This build directory is not removed after the build has been completed. By default a temporary build directory is created which is removed after the build has been completed.
- --build-tag TAG
TAG
is the build tag to be used in the name of the wheel. By default the name of the wheel does not include a build tag.
- --concatenate N
The generated code is split into
N
files. By default one file is generated for each C structure or C++ class. Specifying a low value ofN
can significantly speed up the build of large projects.
- --disable NAME
The
NAME
bindings are disabled and will not be built. This option may be specified multiple times. It is only available if the project contains multiple sets of bindings.
- --disabled-feature TAG
The
TAG
feature tag is disabled. This option may be specified multiple times.
- --enable NAME
The
NAME
bindings are enabled and will be built. Any associated configuration tests that would normally be run to determine if the bindings should be built are suppressed. This option may be specified multiple times. It is only available if the project contains multiple sets of bindings.
- --no-manylinux
Support for
manylinux
in the platform tag of a name of a wheel is disabled. It should only be used if support for older versions of pip is required.
- --minimum-glibc-version M.N
M.N
is the minimum GLIBC version required by the project specified as the major and minor version numbers. This is used to determine the correct platform tag to use for Linux wheels. The default version of GLIBC is v2.5 which corresponds tomanylinux1
. It is ignored if the--no-manylinux
option is specified.
- --name NAME
NAME
is used instead of the PyPI project name in thepyproject.toml
file in the name of the wheel file.
- --debug
A build with debugging symbols is performed.
- --no-docstrings
The generation of docstrings that describe the signature of all functions, methods and constructors is disabled.
- --pep484-pyi
The generation of Python type hints stub files is enabled. These files contain a description of a module’s API that is compliant with PEP 484.
- --protected-is-public
SIP can generate code to provide access to protected C++ functions from Python. On non-Windows platforms this code can be avoided if the
protected
keyword is redefined aspublic
during compilation. This can result in a significant reduction in the size of a generated Python module. This option enables the redefinition ofprotected
and is the default on all platforms except Windows.
- --no-protected-is-public
This option disables the redefinition of
protected
to access protected C++ functions from Python and is the default on Windows.
- --tracing
Debugging statements that trace the execution of the bindings are automatically generated. By default the statements are not generated.