Installation and setup

Getting Started

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.

Choosing a license

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:

1. an instance of CoverageScanner or of the compiler wrappers
2. an instance of the CoverageBrowser
3. 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.

Coco Installation

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 SquishCocoSetup_<x.y.z><platform>.<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 SquishCocoNoncommercial.

• Microsoft^® Windows: The installer is a file SquishCocoSetup_<x.y.z>_Windows_x86.exe or SquishCocoSetup_<x.y.z>_Windows_x64.exe and must be executed.
• Linux™: The installer is a file SquishCocoSetup_<x.y.z>_<platform>.run and 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 SquishCocoSetup_x.y.z_<platform>.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.

Installation of a license server

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 cocolicserver --server-identifier.

• Microsoft^® Windows: In a command window, switch to the project folder and type

  %SQUISHCOCO%\cocolicserver.exe --server-identifier

• 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:

SUQ9YTNmZjk3MDBhMjAwNTU3ZjUzMDFiZTAwClVTU=

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.

Running the license server

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.

Updates

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.