The SIP Command Line — SIP v4.19.19 Reference Guide

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

`-h```

  Display a help message.

`-V```

  Display the SIP version number.

`-a``<FILE>`

  Deprecated since version 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.

`-b``<FILE>`

  The name of the build file to generate. This file contains the information about the module needed by the SIP build system to generate a platform and compiler specific Makefile for the module. By default the file is not generated.

`-B``<TAG>`

  New in version 4.16.

  Deprecated since version 4.19.19.

  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 `%Timeline` directive for more details.

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

`-d``<FILE>`

  Deprecated since version 4.12: Use the `-X` option instead.

  The name of the documentation file to generate. Documentation is included in specification files using the `%Doc` and `%ExportedDoc` directives. By default the file is not generated.

`-D```

  New in version 4.19.1.

  Code is generated for a debug build of Python.

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

`-f```

  New in version 4.18.

  Warnings are handled as if they were errors and the program terminates.

`-g```

  The Python GIL is released before making any calls to the C/C++ library being wrapped and reacquired afterwards. See The Python Global Interpreter Lock and the `ReleaseGIL` and `HoldGIL` annotations.

`-I``<DIR>`

  The directory is added to the list of directories searched when looking for a specification file given in an `%Include` or `%Import` directive. Directory separators must always be `/`. This option may be given any number of times.

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

`-k```

  New in version 4.10.

  Deprecated since version 4.12: Use the `keyword_arguments="All"` `%Module` directive argument instead.

  All functions and methods will, by default, support passing parameters using the Python keyword argument syntax.

`-n``<NAME>`

  New in version 4.19.9.

  The fully qualified name of the private copy of the `sip` module. See also the `--sip-module` option of the installation script.

`-o```

  New in version 4.10.

  Docstrings will be automatically generated that describe the signature of all functions, methods and constructors.

`-p``<MODULE>`

  The name of the `%ConsolidatedModule` which will contain the wrapper code for this component module.

`-P```

  New in version 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.

`-r```

  Debugging statements that trace the execution of the bindings are automatically generated. By default the statements are not generated.

`-s``<SUFFIX>`

  The suffix to use for generated C or C++ source files. By default `.c` is used for C and `.cpp` for C++.

`-t``<TAG>`

  The SIP version tag (declared using a `%Timeline` directive) or the SIP platform tag (declared using the `%Platforms` directive) to generate code for. This option may be given any number of times so long as the tags do not conflict.

`-T```

  Deprecated since version 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.

`-w```

  The display of warning messages is enabled. By default warning messages are disabled.

`-x``<FEATURE>`

  The feature (declared using the `%Feature` directive) is disabled.

`-X``<ID:FILE>`

  New in version 4.12.

  The extract (defined with the `%Extract` directive) with the identifier `ID` is written to the file `FILE`.

`-y``<FILE>`

  New in version 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.

`-z``<FILE>`

  Deprecated since version 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.