Installing and building hipFORT

Installing and building hipFORT#

This topic discusses how to build and install hipFORT from source with CMake. It also provides information on how to build and run the tests.

Prerequisites#

hipFORT requires a Fortran compiler that supports at least the Fortran 2003 standard. AMD amdflang (ROCm’s LLVM Flang, bundled with ROCm) is the recommended default; gfortran version 7.5.0 or newer (see the GFortran website) is also supported. A C compiler is also required: hipFORT enables the C language in CMake so that hip-config.cmake can be used. Please open an issue at ROCm/hipfort#issues if you run into problems. Ready-made CMake toolchain files are provided; see Toolchain files.

Building and testing hipFORT from source#

  1. Ensure you have installed a Fortran compiler and a C compiler (amdflang and amdclang, or gfortran and gcc), git, cmake, and HIP.

  2. Build, install, and test hipFORT from source using the following commands:

    git clone https://github.com/ROCm/hipfort.git
cd hipfort
cmake -S. -Bbuild -DCMAKE_INSTALL_PREFIX=/tmp/hipfort -DHIPFORT_BUILD_NVPTX=OFF -DBUILD_TESTING=ON
cmake --build build
cmake --install build
ctest --test-dir build

    Note

    -DHIPFORT_BUILD_NVPTX=OFF restricts the build to the ROCm backend (hipfort-amdgcn). The CUDA backend archive (hipfort-nvptx) is built by default, so omit the option if you also want it. HIPFORT_BUILD_AMDGCN is the mirror switch: the two are independent, so -DHIPFORT_BUILD_AMDGCN=OFF gives a CUDA-only build. Turning both off is an error. When installing hipFORT from source, you do not need to specify the HIP_PLATFORM environment variable.

Customizing the build#

You can customize the build by setting the following environment variables:

  • FC: The Fortran compiler to use

  • FFLAGS: Compiler flags for building hipFORT

or by setting the CMake cache variables:

  • CMAKE_BUILD_TYPE: Set to RELEASE, TESTING, or DEBUG

  • CMAKE_AR: Static archive command

  • CMAKE_RANLIB: The ranlib used to create the static archive

  • CMAKE_INSTALL_PREFIX: The install directory

  • ROCM_PATH: The ROCm installation root, if it cannot be detected automatically

  • HIPFORT_BUILD_AMDGCN: Build the ROCm (amdgcn) backend archive (ON by default)

  • HIPFORT_BUILD_NVPTX: Build the CUDA (nvptx) backend archive (ON by default)

  • HIPFORT_USE_FPOINTER_INTERFACES: Enable the Fortran 2008 array interfaces (ON by default when the compiler supports Fortran 2008)

  • HIPFORT_ASSUMED_RANK: Use the experimental Fortran 2018 assumed-rank array interfaces instead of the per-rank overloads (OFF by default)

  • HIPFORT_MULTITOOLCHAIN_LAYOUT: Install the modules and the library into compiler-specific subdirectories (ON by default)

  • BUILD_TESTING: Build the CTest suite (OFF by default)

Toolchain files#

Rather than setting the compiler and backend cache variables by hand, you can select a ready-made CMake toolchain file from cmake/toolchains/ with -DCMAKE_TOOLCHAIN_FILE:

cmake -S . -Bbuild -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/amdflang.cmake

Each file only sets the Fortran and C compilers, so they compose with the other build options above. hipFORT is pure Fortran, so no C++ compiler is required.

Linking against hipFORT#

To use hipFORT in your project, invoke your Fortran and HIP compilers directly and link against the appropriate ROCm libraries. hipFORT provides exported CMake targets (such as hipfort::hip, hipfort::rocblas, and hipfort::hipblas) to make this straightforward:

# C is required by the CMake package of HIP, which finds Threads.
project(my_app LANGUAGES Fortran C)

find_package(hipfort REQUIRED COMPONENTS hip hipblas)
add_executable(my_app main.f08)
target_link_libraries(my_app PRIVATE hipfort::hipblas hipfort::hip)

List each library you use as a COMPONENTS entry: a hipfort::<component> target is only defined when that component is requested. The Fortran language must be enabled before find_package(hipfort). See Using hipFORT in your application for the full component list.

The installed CMake package follows the backend the components were exported for. On ROCm, hipfort-config.cmake pulls in libhipfort-amdgcn and resolves each component against its ROCm package. When only the optional CUDA (nvptx) archive is built, it pulls in libhipfort-nvptx instead, offers only the hip* components, and resolves them against CUDAToolkit.

With the nvptx archive, a complex(8) host scalar passed by address, such as alpha or beta given as c_loc(alpha), must be 16-byte aligned: the CUDA libraries access a cuDoubleComplex with an aligned load or store, and a Fortran complex(8) variable is only guaranteed 8-byte alignment. Declaring the scalar allocatable places it on the heap, which is 16-byte aligned.

Examples and tests#

The examples in the f2003 and f2008 subdirectories of the test folder in the repository also serve as tests. The two collections largely overlap, but they are not identical: some tests exist only in one of them. The f2008 tests require the Fortran compiler to support the Fortran 2008 standard or newer. The f2003 tests only require support for the Fortran 2003 standard. The f2003 and f2008 subdirectories are further subdivided into tests for the various hip* and roc* libraries. The test folder also contains an f2018 subdirectory holding an experimental example built on the Fortran 2018 assumed-rank interfaces. That example is only registered with CTest when hipFORT is configured with -DHIPFORT_ASSUMED_RANK=ON (off by default). The openmp subdirectory holds OpenMP target-offload tests, which require an offload-capable compiler.

Building and running the tests#

The tests are driven by CTest. Configure the build with -DBUILD_TESTING=ON, build hipFORT, and run the suite with ctest (see Building and testing hipFORT from source).

The commands below need the ROCm math libraries. The ROCm root is detected from ROCM_PATH or from hipcc on your PATH; override with -DROCM_PATH=.

cmake -S. -Bbuild -DCMAKE_INSTALL_PREFIX=/tmp/hipfort -DHIPFORT_BUILD_NVPTX=OFF -DBUILD_TESTING=ON
cmake --build build
ctest --test-dir build

To run a single test, pass its name to ctest using the -R filter:

ctest --test-dir build -R hipfort_test_f2008_hipblas_dgemm
Contents