squishidl

The squishidl tool parses C++ header files and generates C++ introspection and automation code. This tool is rarely used by customers, and only by those who need to wrap non-Qt classes which do not derive from QObject or have a QMetaObject.

For each C++ header file that is processed, two output files are required: a .h file and a .cpp file. To produce these files, squishidl must be run twice: first to produce the .h file and a second time using the original and generated header files to produce the .cpp file.

The squishidl tool has one small limitation which very occasionally comes to light: the tool cannot wrap the properties of types that have a private assignment constructor or a private copy constructor. This is because Squish's bindings need to copy property values and obviously that isn't possible for types that disallow assignment or copying.

Usage

squishidl <--decl|--impl> -i filename.h [other-options]

The item in angle brackets is required; | signifies alternatives. So here, either the --decl option or the --impl must be specified. The -i (input) option is also required.

Examples

To generate the header file, run squishidl with the --decl (declaration) option, and specify the C++ header that must be parsed with the -i option. For example:

squishidl --decl -i myapp.h -o generated.h

This reads the input header myapp.h and outputs the generated header, generated.h.

To generate the cpp file, run squishidl with the --impl (implementation) option, and specify both the C++ header using the -i option, and the header that was just generated using the -h option. For example:

squishidl --impl -i myapp.h -h generated.h -o generated.cpp

This reads the input header myapp.h and the generated header generated.h, and outputs the generated implementation file generated.cpp.

Options

Many optional values are supported and some can be used multiple times, as indicated by an asterisk, *:

Option	Description
`-o` outputfile	By default, the output is written to the `stdout` stream (such as the console). Use this option to specify a file to write the output to.
`--dump` [dumpfile]	This option is needed when debugging `squishidl` so it should not normally be used. It causes `squishidl`'s intermediate format to be output after parsing the C++ header and being processed by the output generator. By default the output is sent to the `stdout` stream, but if a filename is specified, the output is written to the file instead.
`-D` macro*	Defines a macro on the command line. This works the same way as defining macros for a C++ compiler using the command line. Any macros defined like this when compiling the input file should also be passed to `squishidl`.
`-U` macro*	Undefines a macro on the command line. This works the same way as undefining macros for a C++ compiler using the command line. Any macros undefined like this when compiling the input file should also be passed to `squishidl`.
`-I` includepath*	Adds an include search path in the same way as is done on the command line with a C++ compiler. The same include paths as passed to the C++ compiler when compiling the input file should be passed to `squishidl`.
`-F` path*	Adds include search paths in frameworks. The same frameworks include paths as passed to the C++ compiler when compiling the input file should be passed to `squishidl`.
`--strict`	By default, when parsing the C++ header file, parse errors are interpreted as warnings. Use this option to force `squishidl` to treat parse errors as fatal errors.
`--filter` expr*	Specifies a global function, class, method, or template instantiation, for which introspection code should not be generated. The expr must be the fully qualified signature of a type or of a function. For example, to exclude the `QListIterator` class, use `--filter QListIterator`. And to exclude both of the `QList::erase` methods, the option must be used twice, `--filter "QList::iterator QList::erase(QList::iterator)"` and `--filter "QList::iterator QList::erase(QList::iterator,QList::iterator)"`. The quotes are needed to account for the whitespace between the return type and the method name.
`--nocache`	By default, `squishidl` caches its first run's data in an intermediate format and only parses the C++ header file on the second run if the cache's timestamp has changed. Use this option to switch off `squishidl`'s caching. Using this option will slow `squishidl` down and should usually not be necessary.
`--includePrefix` prefix	Specifies the prefix to use when generating `#include` statements. An empty prefix means the same as specifying the current directory. For example, if the input file has the include `#include <header>` and the `--includePrefix` `../parallel/` is specified, the generated result is `#include <../parallel/header>`.
`--extraInclude` includefile*	Specifies a filename which should appear in the generated file in an `#include` statement.
`--commandFile` filename	Reads the options from the specified command file.

Command Files

Command line options can also be read from a file. The command files are plain text files and contain the command line arguments on a single line or on multiple lines. Using a command file can be convenient if a complex command line is required—especially if the same command line needs to be used repeatedly. Different operating systems have different command line length limits, so if this limit is reached, using a command file can circumvent the problem.

A command file has one or more lines of command-line options, written exactly as they would appear in the command line—including quoting for any whitespace. Blank lines are ignored as are comment lines (those beginning with #).

Here is an example command file called all_my_defines.cmdfile:

# all_my_defines.cmdfile
-D FOO=1
-D BAR=42

You can use the command file with the squishidl tool as follows:

squishidl --impl -i myapp.h -h generated.h -o generated.cpp --commandFile all_my_defines.cmdfile

squishide squishrunner

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.