This section has been prepared from the sip manual written by Wilken Boie, who has graciously given permission to use it in this book.
sip [-h] [-V] [-c dir] [-d file] [-m file] [-I dir] [-s suffix] [-p module] [file]
Table C-2. Command line options
-h display help message -V display the SIP version number -c dir the 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 suffix the suffix to use for C++ source files [default ".cpp"] -p module the name of the generated C++ module [default Module] file the name of the specification file [default stdin]
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
- *.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).
- $(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:
- 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.
- 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.
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.
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: