squishidl

The squishidl tool parses C++ header files and generates C++ introspection and automation code. It is mostly used internally by other Squish tools, although some customers have also found it useful. Since Squish 4, this tool is rarely needed because properties and methods can be automatically detected, even of custom AUT objects.

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, *:

OptionDescription
-o outputfileBy 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.
--strictBy 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.

--nocacheBy 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 prefixSpecifies 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 filenameReads 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

© 2023 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.