PowSyBl - IIDM for C++

Table of contents

• Requirements
  • Ubuntu 20.04
  • Ubuntu 18.04
  • CentOS 8
  • CentOS 7
  • Alpine
  • Windows
  • MacOS
• Build from sources
  • Build the examples
  • Generate the documentation
  • Disable unit tests generation
• Link with powsybl-iidm4cpp
• Contributing

Requirements

To build powsybl-iidm4cpp, you need:

• A C++ compiler that supports C++11 (clang 3.3 or higher, g++ 5.0 or higher)
• CMake (3.12 or higher)
• Make
• Boost development packages (1.65 or higher)
• LibXML2 development packages

Ubuntu 20.04

$> apt install -y cmake g++ git libboost-all-dev libxml2-dev make

Ubuntu 18.04

$> apt install -y g++ git libboost-all-dev libxml2-dev make wget

Note: Under Ubuntu 18.04, the default CMake package is too old (3.10), so you have to install it manually:

$> wget https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz
$> tar xzf cmake-3.12.0-Linux-x86_64.tar.gz
$> export PATH=$PWD/cmake-3.12.0-Linux-x86_64/bin:$PATH

CentOS 8

$> yum install -y boost-devel gcc-c++ git libxml2-devel make wget

Note: Under CentOS 8, the default CMake package is too old (3.11.4), so you have to install it manually:

$> wget https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz
$> tar xzf cmake-3.12.0-Linux-x86_64.tar.gz
$> export PATH=$PWD/cmake-3.12.0-Linux-x86_64/bin:$PATH

CentOS 7

$> yum install -y gcc-c++ git libxml2-devel make wget

Note: Under CentOS 7, the default boost-devel package is too old (1.53), so we install Boost 1.69 from epel-release.

$> yum install -y epel-release
$> yum install -y boost169-devel
$> export BOOST_INCLUDEDIR=/usr/include/boost169
$> export BOOST_LIBRARYDIR=/usr/lib64/boost169

Note: Under CentOS 7, the default CMake package is too old (2.8.12), so you have to install it manually:

$> wget https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz
$> tar xzf cmake-3.12.0-Linux-x86_64.tar.gz
$> export PATH=$PWD/cmake-3.12.0-Linux-x86_64/bin:$PATH

Alpine

$> apk add boost-dev cmake git g++ libxml2-dev make

Windows

Under Windows, install all the following requirements following the vendor instructions:

• Visual Studio Community Edition
• CMake (3.12 or higher)
• Git

To build Boost (1.65 or higher), download the sources from Boost website and uncompress them into a folder. Then open a MSVC prompt and run the following commands:

$> cd <BOOST_SOURCES>
$> bootstrap.bat
$> b2 install -j 4 --with-date_time --with-filesystem --with-program_options --with-system --with-test --layout=system --prefix=<BOOST_PREFIX> variant=<BOOST_BUILD_TYPE> architecture=x86 address-model=64 link=static,shared stage

where BOOST_PREFIX is the folder where Boost libraries will be installed and the BOOST_BUILD_TYPE is the build type (debug or release).

To build LibXml2, download the sources from the GitHub repository and uncompress them into a folder. Then open a MSVC prompt and run the following commands:

$> cd <LIBXML2_SOURCES>/win32
$> cscript configure.js compiler=msvc iconv=no prefix=<LIBXML2_PREFIX>
$> nmake /f Makefile.msvc
$> nmake /f Makefile.msvc install

where LIBXML2_PREFIX is the folder where LibXML2 libraries will be installed.

MacOS

Under MacOS, install all the following requirements following the vendor instructions:

• XCode or Command Line Tools (with xcode-select --install)
• CMake (3.12 or higher)

To install Boost using brew, run the following command:

$> brew install boost

Otherwise, you can build Boost (1.65 or higher) from the sources. First, download the sources from Boost website and uncompress them into a folder. Then open a terminal and run the following commands:

$> cd <BOOST_SOURCES>
$> ./b2 -j 4 --with-date_time --with-filesystem --with-program_options --with-system --with-test --layout=system --prefix=<BOOST_PREFIX> variant=<BOOST_BUILD_TYPE> architecture=x86 address-model=64 link=static,shared stage
$> ./b2 install

where BOOST_PREFIX is the folder where Boost libraries will be installed and the BOOST_BUILD_TYPE is the build type (debug or release).

Note: Depending on the BOOST_PREFIX, we would need root access to install the libraries.

$> sudo ./b2 install

Build the sources

1 - Clone the project

$> git clone https://github.com/powsybl/powsybl-iidm4cpp
$> cd powsybl-iidm4cpp

2 - Configure the project

$> mkdir build
$> cd build
$> cmake .. -DCMAKE_INSTALL_PREFIX=<PREFIX> -DCMAKE_BUILD_TYPE=<BUILD_TYPE>

Available options:

• BUILD_DOXYGEN: Generate the API documentation using doxygen (Default is OFF)
• BUILD_EXAMPLES: Build the examples (Default is OFF)
• BUILD_TESTS: Generate unit tests (Default is ON)
• BUILD_TOOLS: Build the tools (Default is ON)

Note: If you want to use custom version of Boost or LibXML, you would have to help cmake to find the required packages, using the -DCMAKE_PREFIX_PATH options:

$> cmake .. -DCMAKE_INSTALL_PREFIX=<PREFIX> -DCMAKE_PREFIX_PATH=<BOOST_PREFIX>;<LIBXML2_PREFIX>

3. Build the sources

   $> cmake --build .

4. Install the libraries

   $> cmake --build . --target install

Note: With MSVC, to specify the build type, you have to use the --config option instead of -DCMAKE_BUILD_TYPE:

$> cmake --build . --config Release
$> cmake --build . --target install --config Release

Build the examples

To build the examples, you have to pass the -DBUILD_EXAMPLES=ON flag to the configure command, and build the sources:

$> cmake .. -DCMAKE_INSTALL_PREFIX=<PREFIX> -DCMAKE_BUILD_TYPE=<BUILD_TYPE> -DBUILD_EXAMPLES=ON
$> cmake --build .

Click here to see the list of available examples.

Generate the documentation

This project uses doxygen to generate code documentation. To generate the API documentation using doxygen, add -DBUILD_DOXYGEN=ON flag to the configure command line. This will create a new doxygen target.

$> cmake .. -DCMAKE_INSTALL_PREFIX=<PREFIX> -DCMAKE_BUILD_TYPE=<BUILD_TYPE> -DBUILD_DOXYGEN=ON
$> cmake --build . --target doxygen

The HTML documentation is available in <BUILD_DIR>/doc/html/index.html.

Disable unit tests generation

Unit tests generation may be disabled to increase compilation time. When disabled, Boost::unit_test_framework is not necessary to build successfully. To disable tests generation, add -DBUILD_TESTS=OFF flag to the configure command line.

$> cmake .. -DCMAKE_INSTALL_PREFIX=<PREFIX> -DCMAKE_BUILD_TYPE=<BUILD_TYPE> -DBUILD_TESTS=OFF
$> cmake --build .

Link with powsybl-iidm4cpp

We provide cmake script files that make it easy to use powsybl-iidm4cpp in a CMake project, that are installed in the <PREFIX>/LibIIDM/cmake folder.

To use the library in your project, add the find_package instruction to your CMakeLists.txt file:

find_package(LibIIDM REQUIRED)

Then configure your project passing the -DCMAKE_PREFIX_PATH=<IIDM4CPP_PREFIX> option to the cmake command:

$> cmake ... -DCMAKE_PREFIX_PATH=<IIDM4CPP_PREFIX>

A complete example is available here.

Contributing

Checkstyle

This project uses clang-tidy to verify the code style. This tool is provided with the clang extra tools. To enable the code style checking, add the -DCMAKE_CXX_CLANG_TIDY=clang-tidy flag to the configure command.

Code coverage

This project uses either gcov or llvm-cov to compute the code coverage. We also use gcovr (4.2 or higher) to generate both sonar and HTML reports. To compute the code coverage, add the -DCODE_COVERAGE=TRUE flag to the configure command.

Note: To have correct coverage results, you have to disable compiler and linker optimization, compiling the project in Debug mode.

$> cmake .. -DCMAKE_BUILD_TYPE=Debug -DCODE_COVERAGE=TRUE
$> cmake --build .
$> cmake --build . --target test
$> cmake --build . --target code-coverage

The HTML report is available in <BUILD_DIR>/coverage/index.html.