Installation

Build the C++ library with a C++17 compiler and CMake 3.14 or newer, or install the Python bindings directly from PyPI.

Requirements

For the C++ library, install:

  • A C++17-compatible compiler: GCC 8+, Clang 7+, or MSVC 2019+.
  • CMake 3.14 or newer.
  • Git to clone the repository.

For the Python bindings, install a supported Python 3 version and pip.

Build the C++ library

1. Clone the repository 

git clone https://github.com/Raminkord92/PDFxTMD.git
cd PDFxTMD

2. Configure and compile

For GCC, Clang, Ninja, or another single-configuration generator:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

For Visual Studio or another multi-configuration generator:

cmake -S . -B build
cmake --build build --config Release

3. Install the library

Install headers, libraries, and the CMake package configuration:

cmake --install build

For a Visual Studio release build, include the configuration:

cmake --install build --config Release

A custom installation prefix avoids administrator access and makes the installation location explicit:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/path/to/pdfxtmd-install
cmake --build build --parallel
cmake --install build
Data files are separate from the library. Before running an example, download at least one collinear or TMD set and configure its parent directory as described on the PDF sets page.

After installation, use the exported CMake target:

cmake_minimum_required(VERSION 3.14)
project(my_pdfxtmd_app LANGUAGES CXX)

find_package(PDFxTMDLib REQUIRED)

add_executable(my_pdfxtmd_app main.cpp)
target_compile_features(my_pdfxtmd_app PRIVATE cxx_std_17)
target_link_libraries(my_pdfxtmd_app PRIVATE PDFxTMD::PDFxTMDLib)

If CMake cannot find a custom installation, pass its prefix when configuring your application:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/path/to/pdfxtmd-install

For direct compiler linking on Linux or macOS, a minimal command is:

g++ -std=c++17 main.cpp -lPDFxTMDLib -o my_pdfxtmd_app

Non-standard installation locations may also require -I, -L, or a runtime library search path.

Build it as part of another CMake project

CMake’s FetchContent module can download PDFxTMDLib while configuring your application. This is convenient for examples, continuous integration, and projects that want to build a pinned dependency without a separate installation step.

cmake_minimum_required(VERSION 3.14)
project(my_pdfxtmd_app LANGUAGES CXX)

include(FetchContent)

# Keep optional PDFxTMDLib components disabled for a dependency build.
set(ENABLE_BUILDING_WRAPPERS OFF CACHE BOOL "" FORCE)
set(ENABLE_BUILDING_EXAMPLES OFF CACHE BOOL "" FORCE)
set(ENABLE_DOCUMENTATION OFF CACHE BOOL "" FORCE)
set(ENABLE_FORMATTING OFF CACHE BOOL "" FORCE)

FetchContent_Declare(
    PDFxTMDLib
    GIT_REPOSITORY https://github.com/Raminkord92/PDFxTMD.git
    # PDFxTMDLib v1.0.1. Update this SHA deliberately when upgrading.
    GIT_TAG 590a705d498860b9c32076f422e1414b32e1c4da
)

FetchContent_MakeAvailable(PDFxTMDLib)

add_executable(my_pdfxtmd_app main.cpp)
target_compile_features(my_pdfxtmd_app PRIVATE cxx_std_17)

# The source-tree target in v1.0.1 is named PDFxTMDLib.
target_link_libraries(my_pdfxtmd_app PRIVATE PDFxTMDLib)

Configure and build the consuming project normally:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

For Visual Studio or another multi-configuration generator:

cmake -S . -B build
cmake --build build --config Release
Target-name difference in v1.0.1: a source build created through FetchContent exposes PDFxTMDLib, while an installed package found with find_package() exposes PDFxTMD::PDFxTMDLib.
Current release limitation: the v1.0.1 install and CPack rules use top-level source paths. Use this FetchContent method for building and linking the dependency. For installation or packaging of the consuming project, a separate PDFxTMDLib installation is currently the safer approach.

Install the Python bindings

A virtual environment is recommended:

python -m venv .venv

Activate it with .venv\Scripts\activate on Windows or source .venv/bin/activate on Linux and macOS, then install:

python -m pip install --upgrade pip
python -m pip install pdfxtmd

Verify that the module imports:

python -c "import pdfxtmd; print('pdfxtmd imported successfully')"

Troubleshooting

CMake cannot find PDFxTMDLib

Set CMAKE_PREFIX_PATH to the installation prefix, or set PDFxTMDLib_DIR to the directory containing PDFxTMDLibConfig.cmake.

FetchContent cannot download the repository

Confirm that Git is installed and that the configure process can access GitHub through your network or proxy. The first configure requires network access; subsequent builds normally reuse the populated dependency in the build directory.

A set cannot be found

Check that:

  1. The set directory contains its .info file and member .dat files.
  2. The parent directory is listed under paths: in config.yaml.
  3. The set name passed to the API exactly matches the directory and file prefix.

Windows uses the wrong build configuration

Use --config Release for both build and install commands when using Visual Studio.

Continue

Configure data sets Add search paths and understand the expected grid structure. Run a tutorial Choose the C++ or Python interface and evaluate your first distribution.