Installing Squish for Qt from Source Packages

Generally, customers do not need to build the entirety of Squish, but only the parts which must be binary-compatible with the AUT. This includes squishserver, startaut, and wrapper libraries.

Quick Install

If the AUT uses non-standard compiler options or a non-standard Qt configuration, you have to compile parts of Squish from sources using the very same compiler and Qt library that was used for building the AUT.

The Quick Install approach does this:

• limits the components to be built from sources to those which must be binary-compatible with the AUT.
• builds and installs them to <SQUISHDIR>.

A customized version of Squish can be distributed to different computers running the same operating system, as instructed in Distributing and Sharing an Installation.

Basic Requirements

For a build and installation, certain requirements must be met. Some of these requirements concern the Qt library that Squish itself is built with, and some concern the tools used during the build.

• Qt 4.8 or greater must be available.
• A C++ compiler compatible with the version used for building Qt.

Supported Compilers

Squish has been tested on a variety of Windows and Unix-like systems and with several different compilers. Generally, we release a Squish for Qt for each binary release of Qt, for each of our official platforms, using the same compiler that was used to build Qt. You should do the same, if possible, when you build Squish.

The precise compiler requirements depend on what version of Qt you are using. See the links below for more information.

Configure and build

The following steps are based on a Linux/Unix system but will apply to other operating systems in a similar fashion.

It is assumed that a Squish source package has been unpacked into the directory SQUISHSRC. The Major.Minor version number should be the same as your installed Squish.

Start by creating a shell environment that can find the correct compiler as well as the AUT's version of Qt's qmake first in your PATH. This way you do not need to specify --with-qmake= to configure. Verify it is correct by entering qmake --version from that shell.

$ qmake --version
QMake version 3.1
Using Qt version 6.6.3 in /usr/local/Qt/6.6.3/gcc_64/lib

Change into SQUISHSRC, create a SQUISHBUILD directory under that, change into it, and run the configuration script:

$ ../configure --disable-all --enable-idl --enable-qt --enable-server

SQUISHBUILD> ..\configure --disable-all --enable-idl --enable-qt --enable-server

After configure has finished, start the build process:

$ ./build

SQUISHBUILD> build

See Solving Build Errors if you run into problems.

Configure Switches

When invoked, configure tries to automatically detect your system's configuration system and the optimal configuration for Squish. In some cases, the results of the automatic detection or the defaults Squish uses do not match what you want. In these situations it is possible to override the detected and default settings by passing various command line options to configure.

Here are a couple examples:

For a complete list of configure options, execute configure --help on the command line or see configure.

Overriding Build Variables

When configure is run, it will output the configuration it creates—based on the components it automatically detects, but respecting any command line switches we have used to override the automatic detection—into the files config.h and Build.conf.

The config.h file is included with Squish's source code files, and the Build.conf file is used as an input file for the build tool. If the automatic detection produced unsatisfactory results, you could choose to modify these files before running the build application. The variables written to Build.conf can easily be changed, without needing to manually edit the file. This is achieved by specifying arguments of the form VARIABLE=value or VARIABLE+=value at the configure command line. These arguments will replace (if you use =) or extend (if you use +=), the named variables.

Here is an example that replaces a variable's value with a new value; in this case changing the default optimization flag:

configure "CXXOPT=-O1"

And here is another example, in this case we extend the values stored by two variables—the effect of this is to change the gcc compiler's default mode of operation, forcing it to do a 32-bit build on a 64-bit system:

configure "CXXFLAGS+=-m32" "LFLAGS+=-m32"

How to configure a different compiler

The configure script searches your PATH for a C++ compiler, the Qt libraries that Squish depends on, the interpreters and header files for the third-party scripting languages Squish supports—Python, Perl, Ruby, and Tcl—and other system components that Squish may need, such as the Java runtime environment. The output indicates which compiler has been detected. If you are testing Qt applications, you should use the same compiler for Squish that you used to build the AUT.

If you want to force configure to use a different compiler from the one it detected, set the CXX environment variable to the executable of the compiler you want Squish to use, as the following examples illustrate.

$ CXX=g++-9 ../configure

SQUISHBUILD> set CXX=icl
SQUISHBUILD> ..\configure

Next, you run the Squish build tool to compile Squish.

$ ./build

SQUISHBUILD> build

Building Squish can take quite a bit of time, since as part of the process the build tool also creates wrappers for the Qt library.

Installing into SQUISHDIR

This step will probably fail on Windows unless you give yourself write permissions to <SQUISHDIR>, and/or do this step as an administrator.

Before we install, change into <SQUISHDIR> and prepare for the install.

$ rm -r lib/extensions/qt
$ rm lib/libsquishqt*
$ cp etc/paths.ini etc/paths.ini.bak

SQUISHDIR> copy etc\paths.ini etc\paths.ini.bak
SQUISHDIR> rd /q /s lib\extensions\qt
SQUISHDIR> del /q bin\winhook.dll bin\squishqt*.dll

Next, change into SQUISHBUILD and execute the following install command.

$ ./build install DESTDIR=SQUISHDIR

SQUISHBUILD> build install DESTDIR=SQUISHDIR

Finally, we cd back into <SQUISHDIR> and restore etc/paths.ini.

$ mv etc/paths.ini.bak etc/paths.ini

SQUISHDIR> move /Y etc\paths.ini.bak etc\paths.ini

The modified Squish binary package should be ready for use with your application.

Statically-linked Qt Libraries

Recording and running tests is possible with applications built with statically-linked Qt libraries. Here is a summary of the requirements:

1. The correct version/static build of Qt must be installed.
2. The Squish source package must be extracted, configured with the correct options, and built against the static Qt library.
3. Your AUT must be instrumented to use a built-in hook.
4. For squishidl, squishserver, squishide, and squishrunner, you will use a Squish binary package that matches the source package version number.
5. squishserver must be configured so that usesBuiltinHook is set for the AUT.

Instrumenting Your AUT

See Using the Qt Built-in Hook for instructions how to extend your AUT build rules and (if needed) code to make a statically linked Qt application work with the previously built package.

Finally create a new test suite with the appropriate settings and choose the newly instrumented application binary as the Application Under Test.

You should now be able to launch the AUT and record and replay tests.