Run SDK Examples

Run the programs installed with the SDK, then build an example separately against the installed SDK when you want to use it as an application dependency. The commands below keep the example choice generic so the same path works as the examples are updated.

Prerequisites

Complete the examples-enabled build from Build the SDK on AGX Orin. The commands use the default SDK install and library directories.

Enter the example environment

From the SDK source checkout on the target, launch the SDK environment:

WORKSPACE="$HOME/holoscan-5.0"
cd "$WORKSPACE/holoscan-sdk"
INSTALL_DIR="$(./run get_install_dir)"
./run launch "$INSTALL_DIR"

Run the following commands inside the container:

SDK_PREFIX="$PWD"
EXAMPLES_DIR="$SDK_PREFIX/lib/holoscan/examples"

If you configured another install prefix or library directory, set SDK_PREFIX and EXAMPLES_DIR to those paths.

Find an installed example

List the executable programs installed with the SDK:

find "$EXAMPLES_DIR" -maxdepth 3 -type f -perm -111 -print | sort

Installed programs are normally below <example>/cpp/<executable>. The selected program may also need configuration files, model assets, a camera, a display, or another runtime dependency described by its own documentation.

Run an installed example

Set the path of one executable returned by the previous command and run it:

EXAMPLE_PATH="$EXAMPLES_DIR/<example>/cpp/<executable>"
"$EXAMPLE_PATH"

A missing executable usually points to the SDK build or install configuration. If the program starts and then exits with an error, inspect the requirements and diagnostics for that selected example. For execution choices and terminal outcomes, see Running and Stopping.

Build an example against the installed SDK

Build an example as a separate CMake project:

EXAMPLE_SOURCE_DIR="/workspace/holoscan-sdk/examples/<example>/cpp"
EXAMPLE_BUILD_DIR="/workspace/holoscan-sdk/build-consumer-example"

cmake -S "$EXAMPLE_SOURCE_DIR" -B "$EXAMPLE_BUILD_DIR" -G Ninja \
    -DCMAKE_PREFIX_PATH="$SDK_PREFIX" \
    -DCMAKE_CXX_STANDARD=20 \
    -DBUILD_TESTING=ON
cmake --build "$EXAMPLE_BUILD_DIR" --parallel
ctest --test-dir "$EXAMPLE_BUILD_DIR" --output-on-failure

Use the example directory and its standalone CMakeLists.min.txt as the starting point for an application that consumes an installed SDK. A successful CMake configuration confirms that the installed SDK can be found. The test result provides a separate check for the selected program.

Examples with additional requirements

Some programs require CUDA, model files, cameras, displays, or optional SDK components. Check the documentation shipped with the selected example and build the required components before running it. A program that starts but cannot acquire a device is a runtime setup issue, not a CMake configuration issue.

Use exit to leave the container. The source checkout, installation, and consumer build remain in the mounted workspace.

Official documentation

NVIDIA Holoscan SDK User Guide provides the official installation and example guidance.

❯