Standalone Downstream C++ Build Example (#29)

Implement an example of using KvikIO by a downstream C++ project.

The example use  `get_kvikio.cmake` to download and use the KvikIO headers:

```cmake
# Find KvikIO
include(cmake/get_kvikio.cmake)

rapids_find_package(
  KvikIO REQUIRED
  BUILD_EXPORT_SET downstream-example-exports
  INSTALL_EXPORT_SET downstream-example-exports
)

target_include_directories(downstream_example PRIVATE ${KvikIO_INCLUDE_DIR})
```

Authors:
  - Mads R. B. Kristensen (https://github.com/madsbk)

Approvers:
  - Robert Maynard (https://github.com/robertmaynard)
  - Benjamin Zaitlen (https://github.com/quasiben)

URL: #29

ci/gpu/build.sh

@@ -54,6 +54,19 @@ conda info
 conda config --show-sources
 conda list --show-channel-urls
 
+################################################################################
+# TEST - C++
+################################################################################
+
+cd "$WORKSPACE/cpp/examples/downstream"
+
+gpuci_logger "Build downstream C++ example"
+mkdir build
+cd build
+cmake ..
+cmake --build .
+./downstream_example
+
 ################################################################################
 # TEST - Run py.test for kvikio
 ################################################################################

cpp/examples/downstream/CMakeLists.txt

@@ -0,0 +1,33 @@
+# =============================================================================
+# Copyright (c) 2021-2022, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions and limitations under
+# the License.
+# =============================================================================
+
+cmake_minimum_required(VERSION 3.20.1 FATAL_ERROR)
+
+project(
+  KvikIODownstreamExample
+  VERSION 1.00
+  LANGUAGES CXX
+)
+
+# Get CPM see <https://github.com/cpm-cmake/CPM.cmake>
+include(cmake/get_cpm.cmake)
+
+# Get KvikIO see <https://github.com/rapidsai/kvikio>
+include(cmake/get_kvikio.cmake)
+
+add_executable(downstream_example downstream_example.cpp)
+
+# Notice, even though KvikIO is a header-only library, we link to it here.
+# Linking to `kvikio::kvikio` makes CMake include the headers of KvikIO when building.
+target_link_libraries(downstream_example PRIVATE kvikio::kvikio)

cpp/examples/downstream/cmake/get_cpm.cmake

@@ -0,0 +1,21 @@
+set(CPM_DOWNLOAD_VERSION 0.35.5)
+
+if(CPM_SOURCE_CACHE)
+  # Expand relative path. This is important if the provided path contains a tilde (~)
+  get_filename_component(CPM_SOURCE_CACHE ${CPM_SOURCE_CACHE} ABSOLUTE)
+  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+elseif(DEFINED ENV{CPM_SOURCE_CACHE})
+  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+else()
+  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
+endif()
+
+if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
+  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
+  file(DOWNLOAD
+       https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
+       ${CPM_DOWNLOAD_LOCATION}
+  )
+endif()
+
+include(${CPM_DOWNLOAD_LOCATION})

cpp/examples/downstream/cmake/get_kvikio.cmake

@@ -0,0 +1,28 @@
+# =============================================================================
+# Copyright (c) 2022, NVIDIA CORPORATION.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+# in compliance with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software distributed under the License
+# is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+# or implied. See the License for the specific language governing permissions and limitations under
+# the License.
+# =============================================================================
+
+# Use CPM to fetch KvikIO, which makes `kvikio::kvikio` available for `target_link_libraries`
+function(find_and_configure_kvikio MIN_VERSION)
+
+  CPMFindPackage(
+    NAME KvikIO VERSION ${MIN_VERSION}
+    GIT_REPOSITORY https://github.com/rapidsai/kvikio.git
+    GIT_TAG branch-${MIN_VERSION}
+    GIT_SHALLOW TRUE SOURCE_SUBDIR cpp
+    OPTIONS "KvikIO_BUILD_EXAMPLES OFF"
+  )
+
+endfunction()
+
+find_and_configure_kvikio("22.10")

cpp/examples/downstream/downstream_example.cpp

@@ -0,0 +1,34 @@
+#include <iostream>
+
+#include <kvikio/defaults.hpp>
+#include <kvikio/driver.hpp>
+
+using namespace std;
+
+void check(bool condition)
+{
+  if (!condition) {
+    std::cout << "Error" << std::endl;
+    exit(-1);
+  }
+}
+
+int main()
+{
+  cout << "KvikIO defaults: " << endl;
+  if (kvikio::defaults::compat_mode()) {
+    cout << "  Compatibility mode: enabled" << endl;
+  } else {
+    kvikio::DriverInitializer manual_init_driver;
+    cout << "  Compatibility mode: disabled" << endl;
+    kvikio::DriverProperties props;
+    cout << "DriverProperties: " << endl;
+    cout << "  Version: " << props.get_nvfs_major_version() << "." << props.get_nvfs_minor_version()
+         << endl;
+    cout << "  Allow compatibility mode: " << std::boolalpha << props.get_nvfs_allow_compat_mode()
+         << endl;
+    cout << "  Pool mode - enabled: " << std::boolalpha << props.get_nvfs_poll_mode()
+         << ", threshold: " << props.get_nvfs_poll_thresh_size() << " kb" << endl;
+    cout << "  Max pinned memory: " << props.get_max_pinned_memory_size() << " kb" << endl;
+  }
+}