GEOPM 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 :doc:`GEOPM Access Service` and :doc:`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. .. code-block:: bash 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 * ``--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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. TODO this section and runtime->Build Requirements need to be refactored. IMO all this text belongs in the runtime.rst. 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: .. code-block:: bash 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 .. code-block:: make coverage which runs the corresponding unit tests and produces a coverage report in .. code-block:: ./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: .. code-block:: 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: #. The build target (man page) should be added to rst_file in conf.py #. The gzipped installed man page should be listed in the %files section of geopm-doc.spec.in #. 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: .. toctree:: :maxdepth: 1 docu