CMake build instructions

From MCRL2

Contents 1 Introduction 2 Prerequisites 2.1 mCRL2 2.2 CMake 2.3 Boost and wxWidgets 3 Configuration 3.1 Out-of-source builds 3.2 In-source builds 3.3 Alternative Makefile Generation 3.3.1 Command line (WIN, UNIX, MAC) 3.3.2 Graphical (WIN, UNIX, MAC) 3.4 Parameters 4 Compilation 4.1 Unix Makefiles 4.2 Visual Studio 5 Installation 6 Testing 7 Packaging 7.1 Configure packaging for openSUSE 7.2 Configure packaging for Fedora 8 Setup CDash

Introduction

CMake is a cross-platform open-source build system. It consists of a collection of tools that are designed to build, test and package software. CMake is used to control the software compilation process using simple platform and compiler independent configuration files. It generates native makefiles and workspaces that can be used in the compiler environment of your choice.

Currently, the system is developed and tested under Linux with GCC only. The current todo list can be found here.

Prerequisites

mCRL2

A copy of the source tree can be obtained in two ways:

• Download a compressed archive of the source distribution from development version from the download page.

• Use Subversion to checkout a version of the source tree.

The Subversion revision control system is used for storing the source code of the mCRL2 toolset in a repository. Using a Subversion client it is possible to obtain a local copy of the source tree. The following command achieves this:

svn checkout https://svn.win.tue.nl/repos/MCRL2/trunk MCRL2

This creates a local directory MCRL2 with the contents of the trunk directory in the MCRL2 repository. For more information on using SVN see the Subversion website.

CMake

The CMake build system requires a installed copy of CMake (v2.6.2 or higher) to be installed on your system. If your copy does not match the requirements or is simply not available it can be downloaded here.

Boost and wxWidgets

The mCRL2 toolset requires Boost and wxWidgets. If Boost (v1.36 or higher) is correctly installed, CMake will find the installation and use it. If CMake cannot find an install, it is possible to use a stripped internal version of Boost. Graphical tools require wxWidgets. Make sure that a copy is installed. Tools build in debug mode, require a debug version of wxWidgets. Tools that are not build in debug mode, require a release version of wxWidgets. If release tools are linked to debug libraries or vice-versa, it is possible that graphical tools will not work or compilation fails.

Configuration

After the CMake build files are inside the mCRL2 trunk, platform specific makefiles need to be generated for compilation and installation. These Makefiles can be generated inside the source tree or outside the source tree (resp. in-source and out-of-source builds). The advantage of an out-of-source build, is that it allows different build configurations to be maintained concurrently. The preference is given to an out-of-source build. We recommend not to mix in- and out-of-source builds, because they lead to errors when generating makefiles.

Out-of-source builds

For an out-of-source build, create a directory in the location of your choice (indicated by BUILD_DIR):

mkdir BUILD_DIR

Navigate to the directory:

cd BUILD_DIR

Makefiles are generated in BUILD_DIR by executing the following:

cmake /full/path/to/MCRL2

Note: Prior to running this command, the absence of file /path/to/MCRL2/CMakeCache.txt (the location of the SVN checkout) is required, because otherwise no makefiles are generated.

In-source builds

For an in-source build, first navigate to the mCRL2 source directory:

cd /path/to/MCRL2

Makefiles are generated by executing the following command:

cmake .

Note: CMake creates a "Makefile" that overrides the current one in the source directory for UNIX systems. Because boost-build requires this Makefile, users MAY NOT UPLOAD this file. To avoid clashes the "MCRL2_BUILD_IN_SOURCE" variable should explicitly be set to "ON".

Alternative Makefile Generation

It is possible to generate make files differently. Some methods are described below:

Command line (WIN, UNIX, MAC)

ccmake /full/path/to/MCRL2

The "ccmake" executable is the CMake curses interface. Project configuration settings may be specified interactively through this GUI in a terminal. Brief instructions are provided at the bottom of the terminal when the program is running.

Graphical (WIN, UNIX, MAC)

cmake-gui

The "cmake-gui" executable is the CMake curses interface. Project configuration settings may be specified interactively through this GUI. To use this command on Unix/MAC systems, additional packages may be required.

Parameters

The behaviour of generated Makefiles can be altered by using the -D<FLAG=option>. To set a variable, e.g. CMAKE_BUILD_TYPE to Debug, execute the following command (for both in-source and out-of-source builds):

cmake . -DCMAKE_BUILD_TYPE=debug

If the variable CMAKE_BUILD_TYPE is set to Maintainer code coverage will be performed when running tests. wxWidgets is found automatically, if installed. Sometimes it may be convenient to use a version of wxWidgets. If an user want to build with custom version of wxWidgets on Mac and UNIX systems, the user should specify the location (including the file) where wx-config is located. If wxWidgets is compiled and installed in e.g. /USER/Henk/wxWidgetsXYZ/wx-config one should execute the command:

cmake . -DwxWidgets_CONFIG_EXECUTABLE=/USER/Henk/wxWidgetsXYZ/wx-config

Note: Values of the flags are cached and are case insensitive. This implies that when changing a single value, all other flags remain the same. It is also possible to run ccmake instead of cmake with -D.

Here <FLAG=option> needs to be substituted by the variable and value by of your choice. The most important FLAG variables are (default values are indicated by a *):

• CMAKE_BUILD_TYPE: None, Release*, Debug, RelwithDebInfo, MinSizeRel, Maintainer

A variable which controls the type of build when using a single-configuration generator like the Makefile generator. This variable has no effect for Visual Studio projects as they contain multiple-configurations.

• CMAKE_INSTALL_PREFIX: /usr/local/*

The installation prefix for mCRL2, defaulting to /usr/local. All mCRL2 files will be installed there.

• BUILD_SHARED_LIBS: ON* OFF

A variable which controls if the build is static or shared. By default libraries are shared.

• MCRL2_USE_BOOST_INTERNAL: ON*, OFF

A variable that is used if the internal Boost version should be use. By default the internal boost version is used.

• MCRL2_SQUADT_CONNECTIVITY: ON* OFF

A variable that is used to enable connectivity with SQuaDT. By default SQuaDT connectivity is enabled.

• MCRL2_ENABLE_EXPERIMENTAL: ON, OFF*

A variable that controls the build for experimental tools. By default no experimental tools are build.

• MCRL2_ENABLE_DEPRECATED: ON, OFF*

A variable that controls the build for deprecated tools. By default no deprecated tools are build.

• MCRL2_ENABLE_PROFILING: ON, OFF*

A variable that enables profiling when executing tools. By default this option is disabled.

• MCRL2_ENABLE_TEST_TARGETS: ON, OFF*

A variable that enables the build of test targets. This option needs to be enabled in combination with BUILD_TESTING if one wants to execute library tests. By default this option is disabled.

• MCRL2_MAN_PAGES: ON*, OFF

A variable that controls the generation of man-pages. By default this option is enabled.

• MCRL2_MONO_LIB: ON, OFF*

A variable that specifies if the separate libraries are build as one single library. This excludes third party libraries. By default this option is disabled.

• MCRL2_ENABLE_GUI_TOOLS: ON*, OFF

A variable that controls the build of graphical tools. These tools are Diagraphica, Ltsgraph, Ltsview, Squadt (requires SQUADT_CONNECTIVITY) and Xsim. If this value is equal to OFF, no graphical tools are build. By default this option is enabled.

• BUILD_TESTING: ON*, OFF

A variable that enables the execution of tests. If MCRL2_ENABLE_TEST_TARGETS is OFF, only tool tests are executed. If the value for MCRL2_ENABLE_TEST_TARGETS is ON, library tests are also executed. By default this option is enabled.

• CTAGS: /PATH/WITH/FILE/ctags

This variable specifies the location where Ctags can be found. Ctags is a program that generates an index (or tag) file of names found in source and header files of various programming languages.

• DART_TESTING_TIMEOUT: 1500

This variable controls the timeout for running tests.

• MCRL2_INSTALL_BOOST_HEADERS: ON, OFF*

This variable controls the installation of BOOST headers. By default the value is OFF.

• SVNVERSION: /PATH/WITH/FILE/svnversion

This variable specifies the location where svnversion can be found. svnversion is a program for summarizing the revision mixture of a working copy. The program is used to insert the revision number of into the tools.

• wxWidgets_CONFIG_EXECUTABLE: /PATH/WITH/FILE/wx-config

This variable specifies the full pathname to the wx-config utility in your wxWidgets installation (typically this is located in the bin/ subdirectory of your wxWidgets root install. wx-config is a small command-line utility which can help you while building on unix-like systems (including linux and Mac OS X). wx-config will tell what compile flags to use (wx-config --cppflags), tell what link flags to use (wx-config --libs) and manage multiple wxWidgets installs with different configurations (wx-config --list et al).

• wxWidgets_USE_STATIC: ON, OFF*

This variable specifies if the wxWidgets libraries need to be linked static or shared. By default the libraries are used shared. If the toolset is statically build, this value should be changed to OFF.

• wxWidgets_USE_UNICODE: ON*, OFF

This variable specifies if the wxWidgets libraries are use in Unicode. By default the value is equal to ON.

• wxWidgets_wxrc_EXECUTABLE: /PATH/WITH/FILE/wxrc

This variable specifies the full pathname to the wx-rc utility in your wxWidgets installation (typically this is located in the bin/ subdirectory of your wxWidgets root install. The wxrc utility compiles binary xml resource files.

Compilation

Unix Makefiles

After configuration the toolset can be compiled by executing

make

The Makefile provides targets for all tools and libraries. A complete list can be obtained using

make help

Compiling individual targets is useful to speed up incremental builds. For instance, in order to compile the target mcrl22lps, you can execute

make mcrl22lps

Or, if you have only made changes to the tool itself and not to the libraries, you can disable dependency checking by executing

make mcrl22lps/fast

It is possible to build the toolset with multiple threads, by using the j flag. To build the toolset with 8 threads use:

make -j8

Visual Studio

Please use Visual Studio 2010. Graphical tools, that are complied with earlier versions, are known to exit with a segmentation fault as the "vtable" gets corrupt.

Installation

The toolset can be installed by executing the following command in the source tree:

make install

This installs the toolset in the CMAKE_INSTALL_PREFIX directory.

Testing

Before executing tests, make sure that the makefile has been generated with the value of MCRL2_ENABLE_TEST_TARGETS set to YES and the toolset has been compiled once.

To conduct test specified in the source tree execute:

make tests

or

ctest .

To upload the tests to the public dashboard execute one of the following commands. For a nightly build (a build of a svn checkout at 00:00:00 CEST)

ctest -D Nightly 

For an experimental build (used to test new build features) of the current build:

ctest -D Experimental 

For an continuous build of the current build:

ctest -D Continuous 

More available options can be found using using:

ctest -D List 

Note: If multiple Nightly builds are executed, the labels of the buildnames should be disjoint from the other buildname label, in order to avoid the override of earlier builds. To avoid this side-effect, execute cmake and set the BUILDNAME variable with an unique label:

cmake . -DBUILDNAME=label 

Packaging

To build platform specific packages execute the following command:

make package

or

cpack .

To create packages for a specific distribution set the CPACK_SYSTEM_NAME variable to specific distribution by specifying the name, version and architecture.

When package are created for OS-X and Unix, we strongly advise to use the default value for CMAKE_INSTALL_PREFIX, or use a directory value that is available in the target platform.

We advise to use the latest stable version of Cmake and Cpack to generate packages for the various platforms.

Configure packaging for openSUSE

Configure Cmake by:

cmake . -DCPACK_SYSTEM_NAME="`cat /etc/SuSE-release | head -n1 | sed "s/ /\_/g"`"

Configure packaging for Fedora

Create script.sh:

#!/bin/bash
arch="_(`uname -i`)"
fed=`cat /etc/fedora-release | sed 's/ /\_/g'`
echo "$fed$arch"

Then configure Cmake by:

cmake . -DCPACK_SYSTEM_NAME="`script.sh`"

Setup CDash

CDash is an open source, web-based software testing server. CDash aggregates, analyzes and displays the results of software testing processes submitted from clients located around the world.

A generic manual on how to install CDash can be found here.