cuda-samples/cpp/7_libNVVM/README.md

libNVVM and NVVM IR Samples
===========================

Introduction
------------

The following samples illustrate the use of libNVVM and NVVM IR. Running and
testing these samples requires an NVIDIA driver compatible with the CUDA
Toolkit being used for compilation.

- cuda-shared-memory - A directory containing NVVM IR programs that demonstrate
  CUDA 'shared' memory usage.

- cuda-c-linking - Builds an NVVM IR program using the LLVM IR build APIs. It
  will link the generated PTX with a PTX generated by nvcc, and launch the
  linked program on GPU using CUDA driver APIs.

- device-side-launch - Demonstrates launching a kernel within a kernel (CUDA
  dynamic parallelism).

- ptxgen -A standalone NVVM IR program to PTX compiler. It will link the
  libDevice library with the input NVVM IR program, verify the IR for
  conformance to the NVVM IR specification, and then generate PTX.

- simple - Reads in a NVVM IR program from a file, compiles it to PTX, and
  launches the program on GPU using CUDA driver APIs.

- syscalls - A directory containing NVVM IR programs that demonstrate the use of
  device side malloc/free/vprintf functions.

- uvmlite - Demonstrates the use of unified virtual memory.

Steps for Building the Samples
------------------------------

The following environment variables can be used to control the build
process for the samples.  If not specified, CUDA_HOME will be derived by
looking for nvcc in your PATH.  CMake will try to automatically
identify all of these paths.

- CUDA_HOME    : The directory where the CUDA toolkit is installed,
               e.g., /usr/local/cuda.
- LIBNVVM_HOME : The directory where libNVVM components are located.
               e.g., $CUDA_HOME/nvvm.
- LLVM_HOME    : This should point to the install directory if you built llvm
               locally.  This is only required for building the cuda-c-linking
               sample (see the cuda-c-linking note below).

After setting the environment variables and adding the path to the CMake tool
via the PATH environment variable, sample script utils/build.sh (for Linux) or
utils/build.bat (for Windows) may be executed. This script will use build
directory "build" to build the samples, and then install them in the "install"
directory.

If you chose to build using Visual Studio and its integrated CMake support,
then simply run "Build All" and "Install libnvvm-samples."  The installed
samples will be copied to out/install/\<build architecture\>/bin/

Alternatively, we provide a Makefile that will automatically build these
samples on Linux as part of the toplevel cuda-samples build.  Windows users
should build manually via utils/built.bat or Visual Studio's CMake integration.

To build and run the libNVVM samples with CUDA Toolkits 13.0 or newer, user-mode
driver 580 and newer, old kernel-mode drivers (version 550 or earlier)，you must
update the CMake invocation in utils/build.sh or build.bat by adding
`CMAKE_PREFIX_PATH` with a stubs path as follows:
```
-DCMAKE_PREFIX_PATH=/usr/local/cuda/lib64/stubs/
```

A Note About the cuda-c-linking Sample
--------------------------------------

This sample requires a development package (or locally-built) LLVM library,
version 7 or newer.

Which LLVM versions are usable depends on the GPU the sample runs on.  LLVM 15
and newer emit opaque pointers, and libNVVM accepts those only for Blackwell
and later architectures; older architectures require the typed pointers that
LLVM 14 and older emit.  The sample queries libNVVM for the LLVM IR version its
target accepts, so building against a newer LLVM and running on a pre-Blackwell
device reports the requirement and exits with code 2 rather than failing.  Use
LLVM 7 to 14 if you need a single build that runs on any supported device.

The LLVM_HOME environment variable selects which LLVM to build against.  It is
required for users who have a locally built copy of LLVM they wish to use, and
it also picks between installed versions: several LLVM versions install side by
side, so a newer default LLVM does not prevent building this sample against an
older one.  With more than one installed and LLVM_HOME unset, which of them is
found is unspecified, so set it explicitly.  Whichever copy is used has to be a
development install, with the LLVM header files and libraries.

If the LLVM dependencies are met, the user can enable the building of this
sample by setting the CMake variable "ENABLE_CUDA_C_LINKING_SAMPLE" from either
the command line invocation of CMake or by modifying the CMakeLists.txt in this
directory.

Windows users should download LLVM sources from llvm.org and build+install
LLVM locally.  Using the llvm.org provided Windows installer lacks some of
the required components the cuda-c-linking sample depends on.

For Ubuntu users, the "llvm-dev" package contains the LLVM headers and
libraries this sample requires, and is found without any further configuration.
Note that "llvm-dev" is an unversioned metapackage that tracks the
distribution's current LLVM: on Ubuntu 24.04 it installs "llvm-18-dev", which
runs only on Blackwell and later.  To build for an older device, add the
versioned package and select it explicitly:

```bash
sudo apt install llvm-14-dev
LLVM_HOME=/usr/lib/llvm-14 cmake -S . -B build -DENABLE_CUDA_C_LINKING_SAMPLE=1
```

LLVM 15 and newer reference zstd from their CMake package, which the Ubuntu
"llvm-*-dev" packages do not pull in.  Install "libzstd-dev" alongside them,
or CMake fails while loading the LLVM package with a missing
"zstd::libzstd_shared" target.

Windows users will want to build this sample using the same CMake build mode
as they built LLVM with.  For instance if they built LLVM in Release mode,
then this sample should also be built in Release mode. The utils/build.bat can
be updated to reflect this: Add "-DCMAKE_BUILD_TYPE=Release" to the CMake
invocation.