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.

Installing into SQUISHDIR

This step will probably fail on Windows unless you give yourself write permissions to SQUISHDIR, 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.

Detailed Installation Instructions

This section describes in more detail how to perform a build and installation of Squish with other configurations.

Requirements for building SquishRunner

Depending on the configuration, different requirements must be met. The AUT-binary-compatible components must use the right version of Qt. If you are building squishrunner, a set of requirements come up related to the scripting languages you want to use. Squish comes with its own built-in JavaScript interpreter and so does not depend on a third-party JS interpreter. However,

  • Qt must be configured and built as a shared library.
  • To use Python as a scripting language for test scripts, you must have Python 2.7+ or Python 3.8+ installed with development headers.
  • To use Perl as a scripting language for test scripts, you must have Perl 5.18 or any later 5.x version installed.
  • To use Ruby as a scripting language for test scripts, you must have Ruby 1.9 installed.
  • To use Tcl as a scripting language for test scripts, you must have Tcl 8.4 or later installed.

Before building squishrunner, you must make sure that you have the scripting languages you want to use for your test scripts already installed. This does not include JavaScript which is built into Squish.

See the following table regarding what you need to install and where to get it for your platform and scripting language.

LanguageRecommendation
PythonThe Python interpreter executable must be in the PATH. Most Unixes already have Python pre-installed, but if it isn't, a package should be available from your system's package management tool, or you can download a version from http://www.python.org/download/. If you install a package, you must install the -dev or -devel version because Squish needs to access the header files when it is built.
PerlThe Perl interpreter executable must be in the PATH unless you specify a location for it using the --with-perl configure switch. Most Unixes already have Perl pre-installed, but if it isn't, a package should be available from your system's package management tool, or you can download a version from http://www.activestate.com/activeperl/downloads/. If you install a package, you must install the -dev or -devel version because Squish needs to access the header files when it is built.
RubyThe Ruby interpreter executable must be in the PATH unless you specify a location for it using the --with-ruby configure switch. Most Unixes already have Ruby pre-installed, but if it isn't (or is too old a version), a package should be available from your system's package management tool, or you can download a version from http://www.ruby-lang.org/en/downloads/. If you install a package, you must install the -dev or -devel version because Squish needs to access the header files when it is built.
TclMost Unixes already have Tcl installed, but if it isn't, a package should be available from your system's package management tool, or you can download a version from http://www.activestate.com/activetcl/downloads/. If you install a package, you must install the -dev or -devel version because Squish needs to access the header files when it is built.
LanguageRecommendation
PythonWe recommend installing a current Python 3 package available at http://www.python.org/download/.
PerlWe recommend installing ActiveState's Perl package. You can download it from http://www.activestate.com/activeperl/downloads/.
RubyThe official installation page for Ruby is http://www.ruby-lang.org/en/downloads/. Most Linux distributions will have it as a standard package.
TclWe recommend installing ActiveState's Tcl build. You can download it from http://www.activestate.com/activetcl/downloads/.
LanguageRecommendation
PythonA pre-installed version of Python is provided with macOS—this includes the headers and is sufficient for Squish's needs.
PerlA pre-installed version of Perl is provided with macOS—this includes the headers and should be sufficient for Squish's needs.
RubyAt the time of this writing Ruby 1.8 is the pre-installed version on macOS, and this is too old. To use Ruby on macOS you must build and install Ruby 1.9.
TclA pre-installed version of Tcl is provided with macOS—this includes the headers and is sufficient for Squish's needs.

To test embedded Qt applications, see Installing Squish for Qt from Embedded Source Packages.

There are no additional requirements if you want to use JavaScript as a scripting language for test scripts: a JavaScript interpreter is built into Squish. The JavaScript interpreter is automatically built unless JavaScript support is switched off using the configure program's --disable-js switch; see Configure Switches.

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:

--with-qmake=C:\Qt\6.6.3\msvc2019_64\bin\qmake.exeTells configure where the qmake tool is, providing all of the necessary information about your Qt installation to Squish. This is optional if the correct qmake is found first in your PATH.
--with-squishidl=/Applications/Squish_for_Qt/bin/squishidlTells configure where the squishidl executable is located. When building Squish for Qt6, this is not optional. Generally, we need a binary install of Squish to build Squish anyway, as explained in Partial Build.

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

Partial Build

By default, configure builds all the components that it can find.

You can do a partial build by setting particular command line switches for configure that can be used to exclude or include various Squish components.

Squish can be told to build a particular component (providing it can find it) by using --enable-component and replacing component with the name of the component you want to build. Similarly, Squish can be told not to build a particular component by using --disable-component and again, replacing component with the name of the component. In this case, of the one you don't want Squish to build. You can use as many enable and disable command line switches as you need. The components that you can choose to enable or disable are listed below.

--disable-alluse this to disable all Squish's components. Customers should disable this to get a minimal build and then enable only what is needed.
--enable-qtwe are building Squish for a custom Qt. Enable.
--enable-serverthe squishserver application (needed to control the AUT). Enable.
--disable-runneryou can use the binary install's version unless you for some strange reason need to build squishrunner against a custom script engine. Disable.
--disable-python3the Python 3 interpreter. You do not need to enable this unless you are building squishrunner, which you are not.
--enable-32bitif enabled, forces a 32-bit build (if supported by the toolchain).
--enable-pure-qt4if enabled, tells Squish not to use Qt 3 support when testing Qt 4 applications. Squish can detect the lack of Qt3Support automatically in AUTs in many situations when it was unable to in earlier versions. Now, this option is only needed when the Qt installation has Qt3Support but it is not shipped with the AUT.
--enable-qtdebug-libsbuild Squish against Qt debug libraries. You need this option if your AUT is built against a debug build of Qt. The filenames of the debug libraries are different.
--disable-javaJava testing (there should be no reason for customers to build Squish for Java or any other Edition/Toolkit). Don't enable.

You can combine these switches freely within the constraints of internal dependencies. This is where the all component comes in handy:

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

This disables every component except for the server and the Qt wrapper. Basically, this builds all of the components which must be binary-compatible with the AUT.

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.

If configure detected g++ in your PATH, but you want to use an older g++-9, run configure like this:

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

If configure detected MSVC++ but you want to use Intel C++, run configure like this:

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.

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.

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