gputools
========

Building gputools needs the NVIDIA CUDA toolkit, version 11.7 or later
(https://developer.nvidia.com/cuda-downloads), or the equivalent conda
packages:

    conda install -c conda-forge cuda-nvcc cuda-nvrtc-dev cuda-cudart-dev \
        cuda-driver-dev libcublas-dev libcusolver-dev

Running the GPU functions needs an NVIDIA GPU and driver. The package
installs and loads without them; the GPU functions then stop with an error
saying no CUDA device is usable.

If configure cannot find the CUDA toolkit it still installs gputools, but
without its GPU code, and says so loudly ("installed WITHOUT CUDA") in the
install log and when the package is attached. That is also what you get
from a binary built on a machine without CUDA. Make the toolkit findable
(below) and reinstall from source.

Windows
-------

gputools has no native Windows CUDA build: there it installs without its
GPU code. Run R under WSL2 (the Windows Subsystem for Linux), which
supports CUDA, and install gputools there; see
https://docs.nvidia.com/cuda/wsl-user-guide/ for the CUDA toolkit.

Finding CUDA
------------

configure looks for the toolkit in this order:

  1. --with-cuda-home=DIR, or --with-cuda-include=DIR / --with-cuda-lib=DIR
  2. the CUDA_HOME, then CUDA_PATH, environment variable
  3. the directory above nvcc, if nvcc is on the PATH
  4. /usr/local/cuda

For a conda environment, set CUDA_HOME=$CONDA_PREFIX. To pass options:

    R CMD INSTALL --configure-args="--with-cuda-home=/opt/cuda" gputools

Kernels are compiled for the GPU in use the first time each is needed, so
the first call to a function is slower than the ones after it.