BUILDING.md

• Getting started for development
  • Prerequisites
    • Linux
    • MacOS
    • Windows
  • Get the code
  • Building
  • Running unit tests
    • Coverage information
• CMake Configuration Options
  • GILES_BUILD_DOCUMENTATION
  • GILES_CALCULATE_COVERAGE
• Packaging

Getting started for development

Prerequisites

This uses CMake. As such, CMake needs to be installed first. Additionally, Boost needs to be installed manually.

Linux

The recommended way of installing CMake and Boost is through your package manager.

If either package isn't available on your Linux distribution follow the official CMake install instructions or the official boost instructions.

MacOS

CMake and boost can be installed using Homebrew with the following command.

brew install cmake boost-python

Alternatively, follow the official CMake install instructions and the official boost instructions.

Windows

Follow the official CMake install instructions and the official boost instructions.

Get the code

It is highly recommended, but not essential, to use git to get the code. Use this command to get a copy:

git clone --recurse-submodules https://github.com/bristol-sca/GILES

Note that the --recurse-submodules flag is needed.

If downloading manually or without this flag, you will also need to download the projects in the external directory.

Additionally the --jobs flag can be used to speed this process up.

Building

1. Create an empty build directory.

2. From the build directory you just created, run this command. This will generate native build files for your platform. A specific generator can be specified using the -G *generator* flag. A list of generators is available here.

cmake /path-to-source-directory

3. Run this command to compile the code. This will compile the program using your chosen generator e.g. make. Alternatively the native build system can be used manually from this point on.

cmake --build .

Running unit tests

1. Firstly follow the instructions in the Getting started for Development section.

2. Build the tests with this command. This will tell the native build system to build the target called GILES-tests.

cmake --build . --target GILES-tests

3. Run the tests

/path-to-build-directory/bin/tests

Coverage information

In order to generate code coverage information, Gcovr is required.

1. Regenerate the build files using the option shown below from the build directory. This is needed as specific compile flags need to be added in order to generate coverage information.

cmake /path-to-source-directory -DGILES_CALCULATE_COVERAGE=ON

2. Run this command. This will tell the native build system to build the target called coverage.

cmake --build . --target coverage

Coverage information can be found by opening the file coverage.html in the folder coverage which should have been created in your build directory.

/path-to-build-directory/coverage/coverage.html

CMake Configuration Options

These are all CMake options and can be appended to the CMake generate command. For example, from the build directory:

cmake /path-to-source-directory -DGILES_BUILD_DOCUMENTATION

GILES_BUILD_DOCUMENTATION

This option will always built the "doc" target when the target "all" is built. See API Documentation section.

GILES_CALCULATE_COVERAGE

This is needed to generate code coverage information. See Coverage information for details on how to do this.

⚠️ Warning ⚠️ This will enable compile flags that are not recommended for normal purposes. Set this to OFF after you are done generating coverage information.

Packaging

CMake's CPack is used for packaging.

The command to build and package for your current operating system is

cmake --build . --target package --config release

Packaging as an RPM package requires rpmbuild to be installed.