..

_ref-command-line:
The SIP Command Line
====================
The syntax of the SIP command line is::
sip [options] [specification]
``specification`` is the name of the specification file for the module. If it
is omitted then ``stdin`` is used.
The full set of command line options is:
.. program:: sip
.. cmdoption:: -h
Display a help message.
.. cmdoption:: -V
Display the SIP version number.
.. cmdoption:: -a <FILE>
.. deprecated:: 4.18
The name of the QScintilla API file to generate. This file contains a
description of the module API in a form that the QScintilla editor
component can use for auto-completion and call tips. (The file may also be
used by the SciTE editor but must be sorted first.) By default the file is
not generated.
.. cmdoption:: -b <FILE>
The name of the build file to generate. This file contains the information
about the module needed by the :ref:`SIP build system <ref-build-system>`
to generate a platform and compiler specific Makefile for the module. By
default the file is not generated.
.. cmdoption:: -B <TAG>
.. versionadded:: 4.16
The tag is added to the list of *backstops*. The option may be given more
than once if multiple timelines have been defined. See the
:directive:`%Timeline` directive for more details.
.. cmdoption:: -c <DIR>
The name of the directory (which must exist) into which all of the
generated C or C++ code is placed. By default no code is generated.
.. cmdoption:: -d <FILE>
.. deprecated:: 4.12
Use the :option:`-X <sip -X>` option instead.
The name of the documentation file to generate. Documentation is included

in specification files using the :directive:`%Doc` and

:directive:`%ExportedDoc` directives. By default the file is not
generated.
.. cmdoption:: -e
Support for C++ exceptions is enabled. This causes all calls to C++ code
to be enclosed in ``try``/``catch`` blocks and C++ exceptions to be
converted to Python exceptions. By default exception support is disabled.
.. cmdoption:: -f
.. versionadded:: 4.18
Warnings are handled as if they were errors and the program terminates.
.. cmdoption:: -g
The Python GIL is released before making any calls to the C/C++ library
being wrapped and reacquired afterwards. See :ref:`ref-gil` and the
:fanno:`ReleaseGIL` and :fanno:`HoldGIL` annotations.
.. cmdoption:: -I <DIR>
The directory is added to the list of directories searched when looking for
a specification file given in an :directive:`%Include` or
:directive:`%Import` directive. Directory separators must always be ``/``.
This option may be given any number of times.
.. cmdoption:: -j <NUMBER>
The generated code is split into the given number of files. This makes it
easier to use the parallel build facility of most modern implementations of
``make``. By default 1 file is generated for each C structure or C++
class.
.. cmdoption:: -k
.. versionadded:: 4.10
.. deprecated:: 4.12
Use the ``keyword_arguments="All"`` :directive:`%Module` directive
argument instead.
All functions and methods will, by default, support passing parameters
using the Python keyword argument syntax.
.. cmdoption:: -o
.. versionadded:: 4.10
Docstrings will be automatically generated that describe the signature of
all functions, methods and constructors.
.. cmdoption:: -p <MODULE>
The name of the :directive:`%ConsolidatedModule` which will contain the
wrapper code for this component module.
.. cmdoption:: -P

.. versionadded:: 4.10
By default SIP generates code to provide access to protected C++ functions
from Python. On some platforms (notably Linux, but not Windows) 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 disables the generation of the
extra code.
.. cmdoption:: -r
Debugging statements that trace the execution of the bindings are
automatically generated. By default the statements are not generated.
.. cmdoption:: -s <SUFFIX>
The suffix to use for generated C or C++ source files. By default ``.c``
is used for C and ``.cpp`` for C++.
.. cmdoption:: -t <TAG>
The SIP version tag (declared using a :directive:`%Timeline` directive) or
the SIP platform tag (declared using the :directive:`%Platforms` directive)
to generate code for. This option may be given any number of times so long
as the tags do not conflict.
.. cmdoption:: -T
.. deprecated:: 4.16.6
This option is now ignored and timestamps are always disabled.
By default the generated C and C++ source and header files include a
timestamp specifying when they were generated. This option disables the
timestamp so that the contents of the generated files remain constant for a
particular version of SIP.
.. cmdoption:: -w
The display of warning messages is enabled. By default warning messages
are disabled.
.. cmdoption:: -x <FEATURE>
The feature (declared using the :directive:`%Feature` directive) is
disabled.
.. cmdoption:: -X <ID:FILE>
.. versionadded:: 4.12
The extract (defined with the :directive:`%Extract` directive) with the
identifier ``ID`` is written to the file ``FILE``.
.. cmdoption:: -y <FILE>
.. versionadded:: 4.18
The name of the Python type hints stub file to generate. This file
contains a description of the module API that is compliant with PEP 484.

By default the file is not generated.

.. cmdoption:: -z <FILE>
.. deprecated:: 4.16.6
Use the ``@<FILE>`` style instead.
The name of a file containing more command line options.
Command line options can also be placed in a file and passed on the command
line using the ``@`` prefix.