Developer Guide

Publishing package

For publishing the package we use setuptools_scm to manage the versioning of the package based on git tags.

Below are the common commands used for to check the right version is being generated and to create new releases locally.

git checkout -b <branch>
git add <file>
git commit -m <message>
git tag -a <tag> -m <message> # for python use v<MAJOR>.<MINOR>.<PATCH>
pip install setuptools-scm

python -c "
from setuptools_scm import get_version
from setuptools_scm.version import ScmVersion

def myversion_func(version: ScmVersion) -> str:
    from setuptools_scm.version import only_version
    print(f'Debug info:')
    print(f'  Tag: {version.tag}')
    print(f'  Distance: {version.distance}')
    print(f'  Dirty: {version.dirty}')
    print(f'  Node: {version.node}')
    if version.distance > 0:
        result = version.format_next_version(only_version, fmt='{tag}.dev{distance}')
        print(f'  Result (distance > 0): {result}')
        return result
    else:
        result = version.format_next_version(only_version, fmt='{tag}')
        print(f'  Result (distance == 0): {result}')
        return result

version = get_version(version_scheme=myversion_func)
print(f'\nFinal version: {version}')
"

ALCF Polaris

These are steps that are needed to compile dftracer on ALCF Polaris

First, make sure you have set up the environment variable and source it as shown here. Then, you can modify the dftracer codebase and compile the codebase by running commands below:

module use /soft/modulefiles
module load conda
module unload darshan
conda activate base
source <your venv>

export CC=cc
export CXX=CC
export CMAKE_BUILD_TYPE=PROFILE
export DFTRACER_ENABLE_TESTS=On
export DFTRACER_LOGGER_USER=1
export DFTRACER_DISABLE_HWLOC=On
export DFTRACER_TEST_LD_LIBRARY_PATH=/opt/cray/libfabric/1.15.2.0/lib64
pip install -v ".[dfanalyzer]"

Note

We need to disable darshan here because it will give you a lot of segfault on Polaris machine due to POSIX API interceptor done by Darshan

Then, to run the the test, you need to run commands below:

module use /soft/modulefiles
module load conda
module unload darshan
conda activate base
source <your venv>

pip install -r test/py/requirements.txt
pushd build/temp*/*dftracer*/
ctest -E dlio -VV --debug --stop-on-failure
popd

Updating Docs

For updating the docs we need to install additional dependency Sphinx

module use /soft/modulefiles
module load conda
module unload darshan
conda activate base
source <your venv>

pip install "Sphinx<7"

cd <dftracer>/docs
make html

Then open _build/html/index.html

Managing Configuration

Importing config variables in your code is done by including the header file:

Enabling configuration options is done in the cmake/dftracer_config.hpp and the cmake/dftracer_config_dbg.hpp files. These files contain the definitions of configuration options that can be used to control the behavior of the dftracer library. The debug version of the configuration file is used when the DFTRACER_DEBUG macro is defined, allowing for different configurations in debug builds compared to release builds.

Defining the configuration options is done in the CMakeLists.txt file

The code can build with the configuration options by setting the DFTRACER_ENABLE_MY_OPTION option in the CMake configuration step