Installation and setup
This chapter describes the installation and setup of Coco on your machine.
If you have purchased Coco floating licenses, these licenses are managed by a common License Server.
The Coco License Server needs to be installed only once. After it has been installed and set up, you can use the IP address and port number of the license server during Coco installation, instead of a license key.
There are two kinds of licenses, node-locked and floating licenses.
A node-locked license is bound to a specific machine and a specific user account. On that account, you can run as many Coco processes as you like. Note that if you run Coco from a Continuous Integration Server, the server has a separate account, and therefore Coco needs an additional node-locked license.
Floating licenses are bound to processes, not to computers. One needs as many floating licenses as there are Coco processes running at the same time. A Coco process can be:
- an instance of CoverageScanner or of the compiler wrappers
- an instance of the CoverageBrowser
- each instance of the command line tools, cmmerge, cmcsexeimport and cmreport
Every compiler call that is instrumented by Coco is counted separately because it requires one instance of the CoverageScanner to run. Builds with several compilations in parallel should however cause no real problem since a process that cannot get a license will wait until one is freed.
Floating licenses are managed by a license server. The server must be running on a machine that is network-reachable from the machine on which Coco runs. Qt will provide you a license file which determines the maximal number of Coco processes that can be active at the same time. The license server itself is not counted among the processes that need a license.
An installer for Coco can be downloaded from your Qt Account Download area https://account.qt.io/s/downloads.
The installers for the various platforms supported by Coco have a common naming scheme, but the way they must be executed differs. The naming scheme is
.<suffix>, where <x.y.z> is the program version, <platform> describes the operating system and other details of the installation, and <suffix> is an operating system specific suffix. In the noncommercial version,
SquishCoco is replaced by
- Microsoft® Windows: The installer is a file
_Windows_x64.exeand must be executed.
- Linux™: The installer is a file
.runand must be executed with
bash, as in
$ bash SquishCocoSetup_3.3.2_Linux_x86_64.run
Note that the CentOS version of the installer is also valid for RedHat Linux™.
- macOS: The installation package is a file of the form
.pkg. Click it and the installer will be started.
If no valid license is present for your account, the installer will run the License Wizard at the end of the installation to configure the license.
If you have chosen a floating license, you need to choose a machine on your local network on which the license server program runs.
The license server needs a configuration file to run. It specifies the number of licenses served, the machine on which it runs, and the port used by the server. To get the configuration file, Coco must be installed first.
Install Coco on the license server machine. After the installation, cocolicwizard will be started. Ignore it. Instead, from the command line shell, run the command
- Microsoft® Windows: In a command window, switch to the project folder and type
- Linux™: Open a command shell and type
$ /opt/SquishCoco/bin/cocolicserver --server-identifier
- macOS: Open a command shell and type
$ /Applications/SquishCoco/cocolicserver --server-identifier
The program will output a machine ID that looks like this but longer:
Copy it to your clipboard. This will allow you to activate your floating licenses and get a configuration file for running the license server.
Find your Coco subscription on https://account.qt.io/s/my-licenses. Select it, and then go to License Details. On the right, you will find a License Self Activation window. Paste the Machine ID that you got from the previous step here.
The license server's listening port can be specified here too. The default is 49344. In the unlikely event that this port number is already in use, you can specify a different one here.
After entering the values, click Activate. The Activate button will turn into a download button. Click Download Coco Floating License File.
The configuration file is usually called
cocoserver.cfg. With it, the license server can run. In the simplest case, write:
$ /opt/SquishCoco/bin/cocolicserver -c /path/to/cocoserver.cfg
The server then provides licenses to other machines in the same network. Now the IP address of this host, and the server listen port number, can be provided as
host:port to the Coco installer, or the Coco license wizard.
For additional options of cocolicserver, see cocolicserver - license server.
A new license or license server can be specified with cocolic or cocolicwizard.
To update to a newer version of Coco, download and install it. It will then overwrite the previous version. The license will not be touched, you can continue to use it.
If a new compiler is installed, then the Coco installer should be run again, so that Coco becomes aware of the new compiler. This includes new versions of Microsoft® Visual Studio®. If Visual Studio 2013 was present during the Coco installation and Visual Studio 2015 is added, the Coco installer needs to be run.
If instead the compiler is updated, Coco should work mostly without changes.
Note: One exception is the C# compiler. If it is updated, the Coco setup will be overwritten and Coco needs to be reinstalled to make code coverage work again.
Coco v7.0.0 ©2023 The Qt Company Ltd.
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.