Skip to content

Latest commit

 

History

History
124 lines (92 loc) · 5.04 KB

INSTALL.md

File metadata and controls

124 lines (92 loc) · 5.04 KB
Raw

INSTALLATION GUIDE

Requirements

Minimum

  • CMake v3.21 or newer
  • C++17 compiler
  • C11 compiler

Optional

  • Fortan 90 compiler
  • CUDA 9 or later
  • HIP 3.5 or later
  • SYCL 2020 or later
  • OpenCL 2.0 or later
  • OpenMP 4.0 or later

Linux

Configure

OCCA uses the CMake build system. For convenience, the shell script configure-cmake.sh has been provided to drive the Cmake build. The following table gives a list of build parameters which are set in the file. To override the default value, it is only necessary to assign the variable an alternate value at the top of the script or at the commandline.

Example

$ CC=clang CXX=clang++ OCCA_ENABLE_OPENMP="OFF" ./configure-cmake.sh
Build Parameter Description Default
BUILD_DIR Directory used by CMake to build OCCA ./build
INSTALL_DIR Directory where OCCA should be installed ./install
BUILD_TYPE Optimization and debug level RelWithDebInfo
CXX C++11 compiler g++
CXXFLAGS C++ compiler flags empty
CC C11 compiler gcc
CFLAGS C compiler flags empty
OCCA_ENABLE_CUDA Enable use of the CUDA backend ON
OCCA_ENABLE_HIP Enable use of the HIP backend ON
OCCA_ENABLE_DPCPP Enable use of the DPC++ backend ON
OCCA_ENABLE_OPENCL Enable use of the OpenCL backend ON
OCCA_ENABLE_OPENMP Enable use of the OpenMP backend ON
OCCA_ENABLE_METAL Enable use of the Metal backend ON
OCCA_ENABLE_TESTS Build OCCA's test harness ON
OCCA_ENABLE_EXAMPLES Build OCCA examples ON
OCCA_ENABLE_FORTRAN Build the Fortran language bindings OFF
FC Fortran 90 compiler gfortran
FFLAGS Fortran compiler flags empty

Dependency Paths

The following environment variables can be used to specify the path to third-party dependencies needed by different OCCA backends. The value assigned should be an absolute path to the parent directory, which typically contains subdirectories bin, include, and lib.

Backend Environment Variable Description
CUDA CUDATookit_ROOT Path to the CUDA the NVIDIA CUDA Toolkit
HIP HIP_ROOT Path to the AMD HIP toolkit
OpenCL OpenCL_ROOT Path to the OpenCL headers and library
DPC++ SYCL_ROOT Path to the SYCL headers and library

Building

After CMake configuration is complete, OCCA can be built with the command

$ cmake --build build --parallel <number-of-threads>

When cross compiling for a different platform, the targeted hardware doesn't need to be available; however all dependencies—e.g., headers, libraries—must be present. Commonly this is the case for large HPC systems, where code is compiled on login nodes and run on compute nodes.

Testing

CTest is used for the OCCA test harness and can be run using the command

$ ctest --test-dir BUILD_DIR --output-on-failure

Before running CTest, it may be necessary to set the environment variables OCCA_CXX and OCCA_CC since OCCA defaults to using gcc and g++. Tests for some backends may return a false negative otherwise.

During testing, BUILD_DIR/occa is used for kernel caching. This directory may need to be cleared when rerunning tests after recompiling with an existing build directory.

Installation

Commandline installation of OCCA can be accomplished with the following:

$ cmake --install BUILD_DIR --prefix INSTALL_DIR

During installation, the Env Modules file INSTALL_DIR/modulefiles/occa is generated. When this module is loaded, paths to the installed bin, lib, and include directories are appended to environment variables such as PATH and LD_LIBRARY_PATH. To make use of this module, add the following to your .modulerc file

module use -a INSTALL_DIR/modulefiles

then at the commandline call

$ module load occa

Building an OCCA application

For convenience, OCCA provides CMake package files which are configured during installation. These package files define an imported target, OCCA::libocca, and look for all required dependencies.

For example, the CMakeLists.txt of downstream projects using OCCA would include

find_package(OCCA REQUIRED)

add_executable(downstream-app ...)
target_link_libraries(downstream-app PRIVATE OCCA::libocca)

add_library(downstream-lib ...)
target_link_libraries(downstream-lib PUBLIC OCCA::libocca)

In the case of a downstream library, linking OCCA using the PUBLIC specifier ensures that CMake will automatically forward OCCA's dependencies to applications which use the library.

Mac OS

Do you use OCCA on Mac OS? Help other Mac OS users by contributing to the documentation here!

Windows

Do you use OCCA on Windows? Help other Windows users by contributing to the documentation here!