CMake Tutorial

msc8cc edited this page Mar 27, 2012 · 6 revisions

This tutorial describes the use of CMake.

Compile the FREEDM DGI into an Executable

The entry point for CMake is FREEDM/Broker/CMakeLists.txt, which generates a makefile used to compile the FREEDM DGI. This file requires Boost headers and the binaries as described in the guide FREEDM Configuration.

The makefile used to build the FREEDM DGI must be generated using CMake. It can only be generated from the FREEDM DGI root directory, which is located at FREEDM/Broker/

Navigate to FREEDM/Broker/

The makefile is generated using the following command inside the FREEDM/Broker/ directory:

cmake CMakeLists.txt

If an error occurs, verify that Boost is installed correctly or contact a project contributor for assistance. Otherwise you will receive a message similar to:

Build files have been written to: /home/tprfh7/FREEDM/Broker/src

A makefile will be created at FREEDM/Broker/Makefile which can be used to compile the FREEDM DGI code. Compile the code from FREEDM/Broker/ with the following command:


When compilation completes, an executable will be created at FREEDM/Broker/src/PosixBroker which can be used to run the FREEDM DGI. The executable must be run from the src directory or it will not work properly.

Configure the FREEDM DGI Compilation Process

Several compilation options exist that affect how the FREEDM DGI is built. These options can be displayed with their current values using the following command inside of FREEDM/Broker/

cmake CMakeLists.txt -LH

The sample line of output below names an option USE_DEVICE_PSCAD and lists its current value as OFF.

// Enable the PSCAD simulation interface


To enable this option, CMake will have to be used to generate a new makefile. The command would be:

cmake CMakeLists.txt -DUSE_DEVICE_PSCAD=ON

All options are set through the CMake command line argument -DOPTION_NAME=VALUE. OPTION_NAME is determined through the call to cmake CMakeLists.txt -LH demonstrated above. VALUE will most often be either ON or OFF depending on whether the option should be enabled or disabled.

Option settings are stored in the file FREEDM/Broker/CMakeCache.txt and remembered between calls to CMake. This means that once you enable an option, that option will remained enabled until you either disable it or delete the cache file. Extending the previous example, USE_DEVICE_PSCAD will be ON each time you call CMake even if you omit the -DUSE_DEVICE_PSCAD=ON. The only way to disable this option is an explicit call to -DUSE_DEVICE_PSCAD=OFF.

Adding a New Boolean CMake Option

Open FREEDM/Broker/CMakeLists.txt in a text editor and navigate to the list of current options. The sample line below shows the line for the USE_DEVICE_PSCAD option:

option(USE_DEVICE_PSCAD "Enable the PSCAD simulation interface" OFF)

All option specifications have the same format of option(OPTION_NAME "description" DEFAULT_VALUE). If you want to add NEW_OPTION which is OFF until the user decides to enable it, append to the list of current options with the following line:

option(NEW_OPTION "This is an exciting new option!" OFF)

This line is sufficient to allow an option to be viewed, activated, and deactivated as presented in the section on how to configure the compilation process. However, the option is not visible outside of CMakeLists.txt.

If the NEW_OPTION should be visible inside the FREEDM DGI code, open the file FREEDM/Broker/include/config.hpp.cmake. Below is a sample line from this file for the USE_DEVICE_PSCAD option:

#cmakedefine USE_DEVICE_PSCAD

This line will be translated by CMake into either #define USE_DEVICE_PSCAD if the option is enabled or /* USE_DEVICE_PSCAD */ if the option is disabled. Therefore it is sufficient to add the following line to this file to complete the implementation of NEW_OPTION:

#cmakedefine NEW_OPTION

When you want to use the NEW_OPTION inside the FREEDM DGI code, include config.hpp and use NEW_OPTION as an ordinary macro:

#include "config.hpp"

#ifdef NEW_OPTION do new option stuff #endif

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.