Developer Guide

If you wish to modify the source code in the GEOPM git repository, this guide provide instructions for the process.

Before proceeding with the build steps, it’s advisable to familiarize yourself with the build requirements for the GEOPM Access Service and GEOPM Runtime Service.

Developer Build Process

To build all the software in the GEOPM repository, run the following commands described in the repository README.md.

Upon successful build completion, if you wish to execute unit tests, each build has a check target in the makefiles. The geopmdpy and geopmpy directories have a README.md that describes how to run the unit tests.

cd libgeopmd
make -j check
cd ../libgeopm
make -j check

Configuring the Build

Several options can be passed to each of the two configure scripts that determine the build process. The files managed by the scripts are responsible for GEOPM’s version embedding in build artifacts and create two configure scripts using the autotools package.

The configure scripts output several files, including the Makefile used for further build steps. These scripts also accept various command line options and environmental variables that customize behavior. For detailed user documentation, refer to the ./configure –help command. Some notable options and environment variables are listed below:

  • Both configure scripts

  • --prefix: Path prefix for install artifacts

  • --enable-debug: Enable verbose error and warning messaging while disabling optimization.

  • --enable-coverage: Enable coverage report generation with gcov

  • --disable-build-gtest: Use system install of gtest and gmock, do not download or build (version >=1.12.1 required)

  • --enable-beta: Enable beta features, which remain in beta until their interfaces are considered finalized and stable for future releases.

  • export CC=: Set the C compiler with environment variable

  • export CXX=: Set the C++ compiler with environment variable

  • libgeopmd configure script

  • --enable-nvml: Adds support for the Nvidia NVML library

  • --enable-dcgm: Adds support for the Nvidia DCGM library

  • --enable-levelzero: Adds support for OneAPI LevelZero

  • --disable-systemd: Excludes GEOPM service access from PlatformIO

  • --disable-io-uring: Disable support for libiouring for batch IO operations

  • Base configure script

  • --with-geopmd=: Specify the installation location of the service build

  • --disable-mpi: Excludes MPI dependencies from the base directory build

  • --disable-fortran: Excludes Fortran dependencies from the base directory build

  • --disable-openmp: Excludes OpenMP dependencies from the base directory build

  • --disable-geopmd-local: Use system installed geopmd package, do not use local service build

  • export FC=: Set the Fortran compiler with an environment variable

  • export F77=: Set the Fortran 77 compiler with an environment variable

  • export MPICC=: Set the MPI C compiler wrapper with an environment variable

  • export MPICXX=: Set the MPI C++ compiler wrapper with an environment variable

  • export MPIFC=: Set the Fortran compiler wrapper with environmental variable

  • export MPIF77=: Set the Fortran 77 compiler

Intel Compiler and MPI Toolchain

To enable the use of the Intel toolchain for both the compiler and MPI support, export the following variables prior to configuring the base build of the GEOPM repository:

export CC=icx
export CXX=icpx
export FC=ifx
export F77=ifx
export F90=ifx
export MPICC=mpiicc
export MPICXX=mpiicpc
export MPIFORT=mpiifort
export MPIFC=mpiifort
export MPIF77=mpiifort
export MPIFR90=mpiifort

We recommend using the system compiler toolchain for compiling the GEOPM service when creating an installed RPM. The make rpm target of the service directory uses the geopm-service spec file to ensure that the system GCC toolchain is used to create the RPM.

Coverage Instructions

To generate a coverage report, first be sure that you have installed the lcov package. Note that if you are using GCC 9 or above, you must use lcov v1.15 or later to work around this issue.

The lcov source is available here:

https://github.com/linux-test-project/lcov

The GEOPM build must be configured with the “–enable-coverage” option prior to running the tests. Then in either the service directory or the root directory, simply run

make coverage

which runs the corresponding unit tests and produces a coverage report in

./coverage/index.html

Note that all tests must pass in order to generate a coverage report. Any help in increasing code coverage levels is appreciated.

Coverage from the latest release is [posted to our web page](http://geopm.github.io/coverage/index.html).

Coding Style

Python code should follow the PEP8 standard as described in https://peps.python.org/pep-0008/.

C++ code can be corrected to conform to the GEOPM standard using astyle with the following options:

astyle --style=linux --indent=spaces=4 -y -S -C -N

Note that astyle is not perfect (in particular it is confused by C++11 initializer lists), and some versions of astyle will format the code slightly differently.

Use C style variable names with lower case and underscores. Upper camel case is used exclusively for class names. Prefix all member variables with “m“ and all global variables with “g“.

Please avoid global variables as much as possible and if it is necessary to use a global (primarily for C code) please scope them statically to the compilation unit.

Avoid preprocessor macros as much as possible (use enum not #define). Preprocessor usage should be reserved for expressing configure time options.

The number of columns in a source file should not exceed 70 or 80 before wrapping the line. Exceptions are allowed when it is required for compilation or similar. In general, follow the style in the file you are modifying.

Pre-Commit Checks

This repository includes a configuration for pre-commit that uses some of their standard hooks that are relevant to GEOPM, and adds a hook that performs the GEOPM license checks.

To install the pre-commit infrastructure and our configuration:

pip install pre-commit
pre-commit install

Now you will automatically run some checks whenever you make a commit, instead of waiting until you make a pull request to see all of them.

License Headers

Introducing a new file requires a license comment in its header with a corresponding file. Any new installed files should also be added to the package’s .spec file and a debian/*.install file.

Creating Manuals

Introducing a new man page requires changes in multiple files:

  1. The build target (man page) should be added to rst_file in conf.py

  2. The gzipped installed man page should be listed in the %files section of geopm-doc.spec.in

  3. A link to the new html page should be added to the SEE ALSO section of geopm.7.rst and any other related man pages.

Note

In addition, new documentation should follow the style guidelines defined here: