fastPLS system requirements
===========================

fastPLS always builds the CPU backend. CUDA and Apple Metal are optional
acceleration backends and are not required to install the package. On macOS,
Metal is enabled automatically when the system frameworks are available.

CPU-only installation
---------------------

No external GPU software is required. macOS uses Apple Accelerate by default.
On Linux and Windows, fastPLS uses OpenBLAS when it is available and otherwise
uses the BLAS/LAPACK libraries supplied by R. For faster Linux and Windows CPU
execution, install the OpenBLAS development headers and libraries. On Debian or
Ubuntu, install them with:

  sudo apt-get install libopenblas-dev pkg-config

If OpenBLAS is installed outside the standard search path, set OPENBLAS_ROOT
to its prefix before installation. Set FASTPLS_USE_OPENBLAS=1 to require
OpenBLAS explicitly; installation then fails with an informative error if it
cannot be found. Set FASTPLS_USE_OPENBLAS=0 to use the R-supplied libraries.
For source builds intended for repeated large analyses, use a current OpenBLAS
release compiled for the target architecture rather than a generic portable
binary. After installation, use fastPLS::fastPLS_blas() to verify the selected
CPU library, its version, and runtime CPU kernel. Use
fastPLS::fastPLS_blas(details = FALSE) only when a scalar backend name is
required. Older dynamic-architecture builds can
identify themselves as OpenBLAS while selecting a generic or legacy kernel on
a newer processor.

On Windows ARM64, do not point OPENBLAS_ROOT at an x86-64 Rtools or MSYS2
installation. The configuration rejects a cross-architecture archive. If no
ARM64 OpenBLAS development archive is available, leave FASTPLS_USE_OPENBLAS at
its default auto setting to use the BLAS/LAPACK supplied by the ARM64 R build.

CUDA installation
-----------------

CUDA support requires an NVIDIA GPU, a compatible NVIDIA driver and a separate
CUDA Toolkit installation. fastPLS never installs, removes, upgrades or
downgrades the host NVIDIA driver. In particular, do not install Debian's
`nvidia-cuda-toolkit` package merely to build fastPLS on a machine whose vendor
driver already works. Install a compatible NVIDIA CUDA Toolkit separately or
build in a controlled CUDA container that receives the host GPU through the
NVIDIA container runtime.

To request a CUDA build from source, set FASTPLS_USE_CUDA=1. Set CUDA_ROOT,
CUDA_HOME or CUDA_PATH when the toolkit is not installed in a standard
location. The configuration searches include, lib and lib64 directly below the
toolkit prefix and under targets/*/. It then compiles and links a probe against
CUDA Runtime, cuBLAS, cuSOLVER and cuRAND; finding nvcc alone is insufficient.

Examples:

  FASTPLS_USE_CUDA=1 CUDA_ROOT=/usr/local/cuda R CMD INSTALL fastPLS

On Windows, CUDA_ROOT can point to a toolkit directory such as:

  C:/Program Files/NVIDIA GPU Computing Toolkit/CUDA/v12.6

If FASTPLS_USE_CUDA is unset, unavailable CUDA software is ignored and the
package builds in CPU-only mode. Set FASTPLS_REQUIRE_CUDA=1 for strict mode; a
missing header, library, compiler or failed link probe then stops installation.
FASTPLS_CUDA_HOST_CXX may name an absolute system C++ compiler accepted by nvcc.
The default prefers /usr/bin/g++ or /usr/bin/clang++ over CUDA or Conda wrappers.
FASTPLS_CUDA_DIAGNOSTIC_ONLY=1 deliberately builds without CUDA kernels while
marking the installation as diagnostic-only; it is intended for build-system
diagnosis and must not be reported as functional CUDA support.

Apple Metal installation
------------------------

Metal support is available only on macOS. It is detected automatically from the
macOS SDK or system frameworks. To require a Metal build explicitly, set:

  FASTPLS_USE_METAL=1

After installation, run `gpuinfo::has_metal()` to inspect the operating-system
and hardware capability, then request `backend = "metal"` in a small fastPLS
fit to verify this package build. The request fails explicitly when fastPLS was
not compiled with Metal. Set FASTPLS_USE_METAL=0 only to disable Metal
deliberately.

CRAN and hosted build services
------------------------------

Binary packages contain only the capabilities present on the service that built
them. A CPU-only CRAN build remains fully functional. Users who require CUDA,
Metal, or a particular OpenBLAS installation should compile the source package
on the target computer and verify the result with `fastPLS_blas()`,
`fastPLS::cuda_info()`, `gpuinfo::has_cuda()` and `gpuinfo::has_metal()`.

The R dependency gpuinfo (>= 0.2.0) supplies hardware and shared-library
diagnostics. fastPLS::cuda_info() includes that library inventory with a
required_by_fastPLS column. CUDA Runtime, cuBLAS, cuSOLVER and cuRAND are
required for a CUDA build; cuFFT and NCCL are not. The available and status
fields come from fastPLS's own linked runtime. Hardware discovery and a
separate shared-library scan cannot establish package-specific support or
override a working linked backend. Use qualified names because both packages
export cuda_info(). CPU resources and system memory can be inspected through
gpuinfo::cpu_info() and gpuinfo::system_memory_info().
