Installation Guide#

The NPPDx repository is a ready-to-use header layout. There is no top-level NPPDx configure, build, or install step.

Repository layout#

The repository contains:

  • README.md: overview and build instructions

  • LICENSE.txt: license text

  • CONTRIBUTING.md: contribution guidelines

  • include/: NPPDx headers and bundled commonDx headers

  • lib/cmake/nppdx/: NPPDx CMake package configuration

  • lib/cmake/commondx/: commonDx CMake package configuration

  • example/nppdx/: CUDA and Clang PTX examples

The command examples on this page use NPPDX_ROOT as a shorthand for the repository root. It is not required by NPPDx itself. Clone the repository and set it as follows:

git clone https://github.com/NVIDIA/nppdx.git
cd nppdx
export NPPDX_ROOT="$PWD"

On Windows:

git clone https://github.com/NVIDIA/nppdx.git
cd nppdx
set NPPDX_ROOT=%CD%

Linux command examples are shown on the rest of the page with one Windows block as a reference. For Windows, replace environment-variable dereferences ${ENV_VAR} with %ENV_VAR%.

See Requirements and Functionality for CUDA, compiler, and GPU requirements.

NPPDx in a project#

NPPDx is a header-only library. To use it, add the directory containing nppdx.hpp and the bundled commonDx headers to the compilation command. All other requirements are listed in Requirements and Functionality. The easiest approach is to use the NPPDx include directory:

nvcc -std=c++17 -arch=sm_XY (...) -I${NPPDX_ROOT}/include \
     <the_source_file>.cu -o <the_binary>

NPPDx is provided directly as a repository. After cloning into ${NPPDX_ROOT}, nppdx.hpp and the commonDx headers it depends on are available under a single include directory:

${NPPDX_ROOT}/include/

Because the required commonDx headers are bundled next to the NPPDx headers in that same include directory, a single -I${NPPDX_ROOT}/include is sufficient and no additional MathDx include path is needed.

A simple example to start using NPPDx is shown in Image Processing Using NPPDx.

NPPDx in a CMake project#

Add NPPDx to a CUDA target with the package target nppdx::nppdx:

cmake_minimum_required(VERSION 3.30)

project(the_nppdx_app LANGUAGES CXX CUDA)

find_package(nppdx REQUIRED CONFIG)

add_executable(the_nppdx_app main.cu)
target_link_libraries(the_nppdx_app nppdx::nppdx)
set_target_properties(the_nppdx_app PROPERTIES CUDA_ARCHITECTURES "80-real")

Configure the project with CMAKE_PREFIX_PATH pointing at the NPPDx root:

cmake -S /path/to/the_nppdx_app -B build-the-nppdx-app \
      -DCMAKE_PREFIX_PATH="${NPPDX_ROOT}"

Defined variables#

nppdx_FOUND

True if NPPDx was found.

nppdx_INCLUDE_DIR, nppdx_INCLUDE_DIRS

NPPDx include directories (equivalent).

nppdx_commondx_INCLUDE_DIR

commonDx include directory required by NPPDx.

nppdx_LIBRARIES

Libraries to link (nppdx::nppdx).

nppdx_VERSION

NPPDx version number.

Clang device compilation#

The examples include a Clang PTX path that compiles CUDA device code to PTX with Clang and runs a C++ host executable through the CUDA Driver API. Configure with Clang as the C++ compiler:

cmake -S "${NPPDX_ROOT}/example/nppdx" -B build-nppdx-clang-ptx \
      -DCMAKE_CXX_COMPILER=clang++ \
      -DNPPDX_BUILD_CUDA_EXAMPLES=OFF \
      -DNPPDX_BUILD_CLANG_PTX_EXAMPLES=ON \
      -DNPPDX_CLANG_PTX_COMPAT_INCLUDE_DIR=/path/to/cuda-compat/include \
      -DNPPDX_CUDA_ARCHITECTURES=90-real

cmake --build build-nppdx-clang-ptx --target nppdx_examples
ctest --test-dir build-nppdx-clang-ptx --output-on-failure

NPPDX_CLANG_PTX_COMPAT_INCLUDE_DIR must point to a directory containing a cuda_runtime.h entrypoint. That header can come from the CUDA Toolkit include directory. Projects with specialized Clang PTX needs can instead provide a custom cuda_runtime.h with the required definitions. The CMake build force-includes that header for device-only PTX compilation.

For Clang PTX builds, cuda_runtime.h must expose the CUDA vocabulary NPPDx device code uses. When providing a custom compatibility header, ensure it defines (directly or through headers it includes):

  • Qualifiers and attributes: __global__, __device__, __host__, __forceinline__, __shared__, __device_builtin__, __align__, __inline__

  • Launch built-ins: blockIdx, blockDim, threadIdx, and a dim3-compatible type

  • Vector and handle types: cudaTextureObject_t, cudaSurfaceObject_t, uchar2, ushort2, float2, int2, uint3, uchar4, ushort4, int4, float4

  • Vector constructors: make_int2, make_uchar2, make_ushort2, make_float2, make_int4, make_uchar4, make_ushort4, make_float4

  • Texture and surface APIs: tex2D<T>(cudaTextureObject_t, float, float), cudaSurfaceBoundaryMode, and surf2Dwrite overloads for unsigned char, unsigned short, uchar2, ushort2, and uchar4

  • Atomics and control: atomicAdd, atomicCAS (16-, 32-, and 64-bit unsigned), and __trap

  • Device math and utilities: floor, floorf, ceil, ceilf, trunc, truncf, fabs, fabsf, sqrtf, rintf, fminf, fmaxf, __saturatef, __sinf, __cosf, __expf, __powf, __logf, and device printf

Build examples#

Configure and build from example/nppdx. The example CMake project supports:

  • NPPDX_BUILD_CUDA_EXAMPLES: build CUDA examples (default ON)

  • NPPDX_BUILD_CLANG_PTX_EXAMPLES: build Clang device-only PTX examples (default OFF)

  • NPPDX_CUDA_ARCHITECTURES: CUDA architectures for example builds (for example 80-real, 90-real, or 80-real;90-real)

  • NPPDX_CLANG_PTX_COMPAT_INCLUDE_DIR: compatibility include directory providing cuda_runtime.h for Clang PTX examples

Linux:

cmake -S "${NPPDX_ROOT}/example/nppdx" -B build-nppdx-examples \
      -DNPPDX_BUILD_CUDA_EXAMPLES=ON \
      -DNPPDX_BUILD_CLANG_PTX_EXAMPLES=OFF \
      -DNPPDX_CUDA_ARCHITECTURES=80-real

cmake --build build-nppdx-examples --target nppdx_examples
ctest --test-dir build-nppdx-examples --output-on-failure

Windows (Visual Studio Developer Command Prompt or another CUDA-capable CMake environment):

cmake -S "%NPPDX_ROOT%\example\nppdx" -B build-nppdx-examples ^
      -DNPPDX_BUILD_CUDA_EXAMPLES=ON ^
      -DNPPDX_BUILD_CLANG_PTX_EXAMPLES=OFF ^
      -DNPPDX_CUDA_ARCHITECTURES=90-real

cmake --build build-nppdx-examples --target nppdx_examples --config Release
ctest --test-dir build-nppdx-examples -C Release --output-on-failure