# Command Line Tools

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.

The build 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

## 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.

--quiet

  All progress messages are disabled.

--verbose

  Verbose progress messages are enabled.

--api-dir DIR

  A QScintilla `.api` file is created in `DIR`.

--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 is `build`.

--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 of `N` 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 as `public` during compilation. This can result in a significant reduction in the size of a generated Python module. This option enables the redefinition of `protected` 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`. If `DIR` 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 the `site-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 then `NAME` is written as the `Generator` in the `WHEEL` file in the `.dist-info` directory. Otherwise `NAME` is written to the `INSTALLER` file. By default `sip-distinfo` 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 for `NAME` in the `[tool.sip.metadata]` section of the `pyproject.toml` file.

--prefix DIR

  This option is provided as an aid to Linux package builders. `DIR` is used to pass the commonly used values of `DESTDIR` or `INSTALL_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 is `DIR`. This option must be specified.

--requires-dist EXPR

  `EXPR` is added to the list of prerequisites written to the `METADATA` file in the `.dist-info` directory. It is normally used to specify a particular version of a package project’s `sip` module. This option may be specified multiple times.

--wheel-tag TAG

  `TAG` is written as the `Tag` in the `WHEEL` 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.

--quiet

  All progress messages are disabled.

--verbose

  Verbose progress messages are enabled.

--api-dir DIR

  A QScintilla `.api` file is created in `DIR`.

--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 of `N` 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 as `public` during compilation. This can result in a significant reduction in the size of a generated Python module. This option enables the redefinition of `protected` 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`. If `DIR` 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 the `site-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 is `MAJOR`. 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 the `sip` module.

--sdist

  Create an sdist which can then be installed by pip or uploaded to PyPI.

--setup-cfg FILE

  `FILE` is copied to the sdist as `setup.cfg` instead of the default version. This allows the sdist to be customised. A number of macros may be specified in the `setup.cfg` file:

  > `@SIP_MODULE_FQ_NAME@` is replaced by the fully qualified name of the `sip` 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 the `sip` module.

--sip-rst

  Create a `sip.rst` file that documents the Python API implemented by the `sip` 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.

--name NAME

  `NAME` is used instead of the PyPI project name in the `pyproject.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.

--quiet

  All progress messages are disabled.

--verbose

  Verbose progress messages are enabled.

--api-dir DIR

  A QScintilla `.api` file is created in `DIR`. 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 of `N` 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.

--name NAME

  `NAME` is used instead of the PyPI project name in the `pyproject.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 as `public` during compilation. This can result in a significant reduction in the size of a generated Python module. This option enables the redefinition of `protected` 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.