Sip usage and syntax

Wilken Boie

This section has been prepared from the sip manual written by Wilken Boie, who has graciously given permission to use it in this book.

Usage

Invocation, Command Line

sip [-h] [-V] [-c dir] [-d file] [-m file] [-I dir] [-s suffix] [-p module] [file]

where:

Table C-2. Command line options

-hdisplay help message
-Vdisplay the SIP version number
-c dirthe name of the code directory [default not generated]
-d file the name of the documentation file [default not generated]
-m file the name of the Makefile [default none generated]
-I dir look in this directory when including files
-s suffixthe suffix to use for C++ source files [default ".cpp"]
-p modulethe name of the generated C++ module [default Module]
filethe name of the specification file [default stdin]

Limitations

The following limitations are SIP compile time options:

  • Maximum number of arguments to a function: 20

  • Maximum nesting depth of %If directives: 10

  • Maximum number of nested version qualifiers in the generated Python: 10

  • Maximum number of option flags in function declarations: 5

Files

Source Files

*.sip

and possibly further included files are processed by SIP. They are the source file(s) defining the wrapping. They closely resemble the header files they describe but also contain additional directives for a range of special cases and purposes (e.g. production of documentation, treatment of different versions a wrapped libraries).

Files containing the wrapping

$(module).py

is produced by SIP. It initializes the wrapping and imports the dynamic lib lib$(module)c.pyd which contains the actual C++ wrapping code.

Code from %PrePythonCode and %PythonCode sections is also placed in this file as in the following example (assuming a module MOD wrapping classes A and B):

 
# Python wrapper code 
# Copying: Copyright (c) .... 
import libMODc libMc.sipInitModule() 

# here comes code from %PrePythonCode sections 

class  A: 
... 
class B: 
... 
libMc.sipRegisterClasses() 
# here comes code from %PythonCode sections
                  
lib$(module)c.pyd

This dynamic library is compiled from the following, SIP generate intermediate files:

Intermediate Files

sip$(module)$(class).h, sip$(module)$(class).cpp

A pair of corresponding header and C++ files for each wrapped class.

sip$(module)Decl$(module).h

A global module header, which (beside all im- and exports) contains all %ExportedHeaderCode and %HeaderCode (from imported .sip files only %ExportedHeaderCode).

$(module)cmodule.cpp

Which contains the module global and initialisation code.

Auxilliary Files

makefile_name

If SIP option "-m makefile_name" is given, one of a set of makefile templates (defined in the SIP files) is seletected and instantiated with the appropriate module and class names. It is typically used to compile the wrapping.

sip_helper.cpp

All code from %VersionCode sections will be placed in this file. Typically it is compiled into sip_helper.exe, which then produces sip$(module)Version.h. This is included in all relevant files to maintain version information for the conditional sections.

Why not just #include the necessary file that provides the version information and use the C++ test specified as part of the version definition in the .sip files?

The answer is that moc can't handle C++ pre-processor commands, so the proxy header file must be run through the C++ pre-processor beforehand. The code generated by moc is then #included by the main module code.

The net result is that the header file specifying the version information is #included by the main module code and #included a second time - but the second time is a version that has already been run through the C++ pre-processor and has therefore lost it's usual means of protecting itself from being #included twice.

Unless the file follows certain rules (like having no function definitions) it is likely to make the C++ compiler complain. Therefore the solution is to use a generated file that isn't going to cause complaints.

docfile_name

If SIP option "-m docfile_name" is given, documentation records are extracted from the SIP file(s) and written to docfile_name.

.sip File Syntax

General rules

  • All %keywords must start at beginning of line.

  • All _block_s must be closed by a matching %End directive.

  • Parameters are separated by whitespace, string parameters are enclosed by double quotes.

Macros

A number of macros can be used in the .sip files (e.g. class definitions, makefile templates). When SIP parses the definitions, the macros are replaced by actual values as follows:

Table C-3. Macros in Makefile Templates

$$a '$' character
$CClass name
$SSource files
$OObject files
$cC++ file suffix
$oObject_file_suffix
$mC++ module name
$PPercent sign