DRM library build & test

This section explain in detail how to build and test the library. This section is only useful for DRM library contributors, if you simply want to install the library, see DRM Library installation.

CMake options are used to select which components are generated amongst the following ones:

Documentation
Python wrapper
Testing materials
Reporting materials

For more details about available CMake options, refer to Build CMake configuration.

Requirements

Minimal requirements

Utilities:

git
cmake >= 3.12
make (Or any CMake supported build tool)
GCC, G++ >= 4.8 (Or any compatible C++11 compiler)

Libraries:

libcurl-devel
jsoncpp-devel

Run following commands to install requirements:

On Debian 10 and more, Ubuntu 18.10 and more

# Ensure Apt cache is up to date
sudo apt update

# Install packages
sudo apt install -y git make g++ libcurl4-openssl-dev libjsoncpp-dev cmake

On Debian < 10, Ubuntu < 18.10

# Ensure Apt cache is up to date
sudo apt update

# Install packages
sudo apt install -y git make g++ libcurl4-openssl-dev libjsoncpp-dev

# Ensure Pip3 is installed
sudo apt install -y python3-pip

# Install a recent version of Cmake using pip
sudo pip3 install -U cmake

On RHEL 8, CentOS 8, CentOS Stream 8

# Ensure EPEL repository is installed
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

# Install packages
sudo dnf install -y git make gcc gcc-c++ libcurl-devel jsoncpp-devel

# Ensure Pip3 is installed
sudo dnf install -y python3-pip

# Install a recent version of Cmake using pip
sudo pip3 install -U cmake

On RHEL 7, CentOS 7

# Ensure EPEL repository is installed
sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

# Install packages
sudo yum install -y git make gcc gcc-c++ libcurl-devel jsoncpp-devel

# Ensure Pip3 is installed
sudo yum install -y python3-pip

# Install a recent version of Cmake using pip
sudo pip3 install -U --prefix /usr cmake

On Fedora

sudo dnf install -y git make gcc gcc-c++ libcurl-devel jsoncpp-devel cmake

Python 3 library option

This step is required only if you want to:

Generate the Python 3 library (using -DPYTHON3=ON option with CMake)
Generate the Sphinx documentation (using -DDOC=ON option with CMake)
Complete the Run tests section.

Otherwise you can jump to the next step.

Packages:

Python3-devel

Python packages:

setuptools
wheel
cython >= 0.28

Run following command to install requirements:

On Debian, Ubuntu

sudo apt install -y python3 python3-dev python3-pip
sudo pip3 install -U setuptools wheel cython

On Fedora, RHEL 8, CentOS 8, CentOS Stream 8

sudo dnf install -y python3-devel python3-pip
sudo pip3 install -U setuptools wheel cython

On RHEL 7, CentOS 7

sudo yum install -y python3-pip python3-devel
sudo pip3 install -U --prefix /usr setuptools wheel cython

Documentation generation option

This step is required only if you want to:

Generate the C/C++ documentation (using -DDOC=ON option with CMake)
Generate the full Sphinx documentation (using -DDOC=ON -DPYTHON3=ON options with CMake)

Otherwise you can jump to the next step.

Utilities:

doxygen

Python packages (Required for full documentation):

sphinx
breathe
sphinx_rtd_theme

Run following command to install requirements:

On Debian, Ubuntu

sudo apt install -y doxygen
sudo pip3 install -U sphinx breathe sphinx_rtd_theme

On CentOS 8, CentOS Stream 8

sudo dnf config-manager --set-enabled PowerTools
sudo dnf install -y doxygen
sudo pip3 install -U sphinx breathe sphinx_rtd_theme

On RHEL 8

sudo subscription-manager repos --enable "codeready-builder-for-rhel-8-$( /bin/arch )-rpms"
sudo dnf install -y doxygen
sudo pip3 install -U sphinx breathe sphinx_rtd_theme

On RHEL 7, CentOS 7

sudo yum install -y doxygen
sudo pip3 install -U --prefix /usr sphinx breathe sphinx_rtd_theme

On Fedora

sudo dnf install -y doxygen
sudo pip3 install -U sphinx breathe sphinx_rtd_theme

Test generation option

Warning

This dependency is mandatory to complete the Run tests section.

This step is required only if you want to:

Run the test suite (using -DTESTS=ON option with CMake)

Otherwise you can jump to the next step.

Python packages:

pytest

Run following command to install requirements:

On RHEL 7, CentOS 7

sudo pip3 install -U --prefix /usr pytest flake8 pytest-ordering

On others

sudo pip3 install -U pytest flake8 pytest-ordering

Package generation option

This step is required only if you want to:

Generate the installation packages (using -DPKG=ON option with CMake)

Otherwise you can jump to the next step.

Before going further, make sure the section Python 3 library option has been completed.

RPM package (For RHEL, CentOS, Fedora)

Required to build packages:

rpm-build

Required to sign packages:

rpm-sign
gnupg

To install the required utilities, run the following command:

On Fedora, RHEL 8, CentOS 8, CentOS Stream 8

sudo dnf install -y rpm-build rpm-sign gnupg

On RHEL 7, CentOS 7

sudo yum install -y rpm-build rpm-sign gnupg

DEB Packages (For Debian, Ubuntu)

Required to build package:

pkg-config
dpkg-dev
file

Required to sign packages:

dpkg-sig
gnupg

To install required utilities, run the following command:

sudo apt install -y pkg-config dpkg-dev dpkg-sig gnupg file

ABI check option

This step is required only if you want to:

Run the test suite in Debug mode (using -DCMAKE_BUILD_TYPE=Debug option with CMake)

Otherwise you can jump to the next step.

Utilities:

abi-compliance-checker

To install requirements run the following command:

On Debian 9 or more, Ubuntu 18.04 or more

sudo apt install -y abi-compliance-checker abi-dumper

On Debian < 9, Ubuntu < 18.04

# ABI compliance checker is not available as package for theses version and
# needs to be installed manually.
sudo apt install -y libelf-dev elfutils dh-autoreconf exuberant-ctags
git clone https://github.com/lvc/abi-compliance-checker --depth 1
cd abi-compliance-checker
make -j
make install
cd ..
git clone https://github.com/lvc/abi-dumper --depth 1
cd abi-dumper
make -j
make install
cd ..

On Fedora, RHEL 8, CentOS 8, CentOS Stream 8

sudo dnf install -y abi-compliance-checker

On RHEL 7, CentOS 7

sudo yum install -y abi-compliance-checker

Coverage option

This step is required only if you want to:

Compile the C/C++ with the -coverage option (using -DCOVERAGE=ON option with CMake)
Generate the coverage report after the test suite execution in Debug (using -DCMAKE_BUILD_TYPE=Debug -DTEST=ON -DCOVERAGE=ON options with CMake)

Otherwise you can jump to the next step.

Utilities:

lcov

Python packages:

pytest-cov

Run following command to install requirements:

On Debian, Ubuntu

sudo apt install -y lcov
sudo pip3 install -U pytest-cov

On Fedora, RHEL 8, CentOS 8, CentOS Stream 8

sudo dnf install -y lcov
sudo pip3 install -U pytest-cov

On RHEL 7, CentOS 7

sudo yum install -y lcov
sudo pip3 install -U --prefix /usr pytest-cov

Automation with tox

This step is required only if you want to use tox to automate some execution scenarios. Otherwise you can jump to the next step.

Python packages:

tox

Run following command to install requirements:

On RHEL 7, CentOS 7

sudo pip3 install -U --prefix /usr tox

On others

sudo pip3 install -U tox

Build CMake configuration

Clone Accelize DRM library repository and move to it:

git clone https://github.com/Accelize/drm.git --recursive --depth 1
cd drm

Create a build directory and move to it:

mkdir build
cd build

Run CMake to build your configuration:

cmake ..

Use the following options to build optional components:

-DPYTHON3=ON: Build Python library as a wrapper of the C/C++ library
-DDOC=ON: Build documentation. The Python library is required to get the full library documentation in Sphinx HTML format. Otherwise only the documentation for the C/C++ API is generated in Doxygen HTML format.
-DTESTS=ON: Generate the testing materials and run test suite.
-DCOVERAGE=ON: If -DTESTS=ON, compile with coverage support.
-DPKG=ON: Generate the installation packages.
-DCMAKE_BUILD_TYPE=Debug: Compile in Debug mode.
-DAWS=ON: Run full test suite when executed on AWS f1 instance.

Note

Building the development package requires both -DPYTHON3=ON and -DDOC=ON options.

Building Python Library and Sphinx-like documentation

cmake -DPYTHON3=ON -DDOC=ON ..

Compile CMake configuration

Once the CMake configuration built, you can either:

Compile:
```
make -j
```
From here you can test your compiled library in section Run tests.
or you can directly install the library on your system:
```
sudo make install
```
From here you can test your compiled library in section Run tests.
or you can build the installation packages (Require cmake -DPKG=ON option):
```
make package
```

Generated output

Depending on your CMake configuration, the build directory will contain the following components:

C++ library named as libaccelize_drm
C library named as libaccelize_drmc
C/C++ headers located in include directory.
Python library located in python3_bdist directory.
Python library sources located in python3_src directory.
Packages located in packages directory.
Documentation in HTML format located in doc_html directory.

Run tests

This section explains how to run Accelize DRM python library tests.

Warning

Following tests require a real FPGA board and associated driver installed. Refer to supported_os paragraph in DRM Library installation to get the list of tested OS.

Important

The tests described below are based on the Python DRM library and pytest module. So make sure sections Python 3 library option and Test generation option have been completed and that you have run the CMake command with the -DTESTS=ON -DPYTHON3=ON options.

Test command

Usage

Here is the test command:

# LD_LIBRARY_PATH must be set to the "build" directory so that
# the library can be directly imported in the build environment.
export LD_LIBRARY_PATH=path_to_build_directory

# Run tests with pytest
pytest --cred=path_to_cred.json [options]

Warning

Depending on your execution platform environment and the driver requirements you might need to execute the comment with sudo:

sudo LD_LIBRARY_PATH=path_to_build_directory pytest --cred=path_to_cred.json [options]

path_to_cred.json is the path to your credentials file. For more details refer to the section ‘Credentials file’ in Configuration

Command options are:

--backend=<c++|c>: Select library API to use as backend (Supported from pytest only). Default: c++.
--fpga_driver=key_name: Select FPGA driver to use. Default: aws_f1. Possibles key_name values: * aws_f1: Amazon Web Service FPGA instances (f1.2xlarge, f1.4xlarge). * xilinx_xrt: Xilinx XRT.
--fpga_slot_id=integer: Set FPGA slot. Default: 0.
--drm_controller_base_address=address: Set DRM Controller IP base address. Default: 0.
--cred=json_path: Specify the path to a cred.json file containing valid Accelize credentials to use as base to run tests. Default: ./cred.json.
--server=url: Specify metering server URL. Default: https://master.metering.accelize.com
--loglevel=<0..4>: Specify Accelize DRM library verbosity. Possibles values: 0 to 5. Default: 4.
--logformat=<0|1>: Specify library log format: 0=short format, 1=long format.
--fpga_image=image: Select FPGA image to use for program the FPGA. By default, use default FPGA image for the selected driver and last HDK version. Set to empty string to not program the FPGA.
--hdk_version: Select FPGA image based on Accelize DRM HDK version. By default, use default FPGA image for the selected driver and last HDK version.
--integration: Run integration tests, needs 2 FPGA.
--endurance: Run endurance tests, might require 2 FPGA.
--cov=accelize_drm: Run test with pytest-cov options to enable Python library coverage

Coverage

Important

To enable coverage reporting the section Coverage option must have been performed.

Use –cov=accelize_drm option to enable the coverage with the test execution:

sudo LD_LIBRARY_PATH=path_to_build_directory pytest --cred=~/my_application/cred.json --cov=accelize_drm

The C/C++ library coverage is generated using gcov and can be retrieved and gathered with python coverage using lcov as follows:

lcov --capture --directory . --output-file coverage.info -q >/dev/null 2>&1
lcov -r coverage.info '/usr/include/*' '*/drm_controller_sdk/*' -o coverage.info -q
lcov --list coverage.info
genhtml coverage.info -q --legend -o coverage

The result is an HTML report located in the coverage directory.

Note

To enable coverage the CMake configuration must contain the -DCOVERAGE=ON -DCMAKE_BUILD_TYPE=Debug options.

Note

This procedure is fully and automatically managed using tox. See Run tests partially for more details.

Run full tests

This scenario performs following actions:

Build the library in debug, release and/or install mode.
Get library for packages (install mode only).
Run Both C and C++ backend tests.
Run Integration tests.
Install libraries (install mode only).
Generate documentation (except in debug mode).
Generate and export packages (release mode only).
Combine all tests coverage and generate Python/C/C++ coverage report (debug mode only).

For simplicity and efficiency the tox utility is used to execute these scenarios. Make sure the Automation with tox section has been performed.

Tox tests must be executed from the DRM library root directory where the tox.ini file is located. The usual test options can be used after the -- delimiter.

Running the full scenario

tox -- --cred=~/my_application/cred.json [options]

Note

The --backend option is not supported because managed by tox.

Warning

Running Tox with sudo may be required to run build-install scenario and to access FPGA in c and cpp scenarios.

Run tests partially

It is possible to reduce the scenario scope with the -e tox argument. More information on tox documentation.

Some examples:

Build and run all tests with coverage in debug mode
tox -e build-debug,cpp-debug,c-debug,integration-debug,coverage-debug -- --cred=~/my_application/cred.json
Coverage reports can be found in the report directory in the tox debug build environment (By default: ./.tox/debug/build/report)

Build and run c and c++ tests in release mode

tox -e build-release,cpp-release,c-release -- --cred=~/my_application/cred.json

Build and export packages

# Specify packages export directory
export PACKAGES_DIR="~/packages"

# Build and export
tox -e build-release,export-release

Build, install (using “make install”) and run tests

sudo tox -e build-install,cpp-install,c-install -- --cred=~/my_application/cred.json

Install from packages and run tests

# Get packages, by example build from a previous release scenario
export PACKAGES_DIR="./.tox/release/build/packages"

# Install packages and run tests
sudo tox -e package-install,cpp-install,c-install -- --cred=~/my_application/cred.json

If your platform has 2 FPGA on 2 different PCIe slots, you can optimize the execution time by parallelizing some tests with the -p all option:

Note

In this case, the --fpga_slot_id is not supported because managed by tox.

Running full scenario in parallel

tox -p all -- --cred=~/my_application/cred.json