5.1.1. Building AOCL-LAPACK from Source#

GitHub URL: amd/libflame

Prerequisites

The following dependencies must be met for installing AOCL-LAPACK:

• Target CPU ISA supporting AVX2 and FMA

• Python

• CMake

• GCC, g++, and Gfortran

• AOCL-Utils library

• AOCC

For more information on validated versions of compiler, CMake and Python, refer to Validation Matrix.

Build Steps

AOCL-LAPACK supports compiling the library using CMake build system in addition to configure script method on Linux. Both the approaches to build the library are explained in this section.

Complete the following steps to build AOCL-LAPACK from source:

1. Clone the Git repository (amd/libflame.git).

2. Compile AOCL-LAPACK source.

Method 1: Using CMake

AOCL-LAPACK can be linked with any Netlib BLAS compliant library when compiled with standard CMake options. However, AOCL-LAPACK provides an option to explicitly link with AOCL-BLAS library at compile time. This option enables tighter coupling between AOCL-LAPACK and AOCL-BLAS by invoking lower level AOCL-BLAS APIs directly and that could result in better performance for certain APIs on AMD “Zen” CPUs. It is recommended to link with AOCL-BLAS library by providing the option ENABLE_AOCL_BLAS in the CMake configuration as described in steps below.

1. Create a new build directory, for example, newbuild:

   $ mkdir newbuild
   $ cd newbuild
   

2. Run the following command to configure the project:

   Set header file path of the AOCL-Utils library using the LIBAOCLUTILS_INCLUDE_PATH option:

   • With GCC (default):

     $ export AOCL_ROOT="<path to AOCL-BLAS install directory>"
     
     **Using 32-bit Integer (LP64)**
     
     $ cmake ../ -DENABLE_AMD_FLAGS=ON -DENABLE_AOCL_BLAS=ON
     -DCMAKE_INSTALL_PREFIX=<your-install-dir>
     -DLIBAOCLUTILS_INCLUDE_PATH=<path_to_libaoclutils_header_files> -D
     LIBAOCLUTILS_LIBRARY_PATH=<path_to_libaoclutils library>
     
     **Using 64-bit Integer (ILP64)**
     
     $ cmake ../ -DENABLE_ILP64=ON -DENABLE_AMD_FLAGS=ON
     -DENABLE_AOCL_BLAS=ON -DCMAKE_INSTALL_PREFIX=<your-install-dir>
     -DLIBAOCLUTILS_INCLUDE_PATH=<path_to_libaoclutils_header_files> -D
     LIBAOCLUTILS_LIBRARY_PATH=<path_to_libaoclutils library>
     

   • With AOCC:

     $ export CC=clang
     $ export FC=flang
     $ export FLIBS="-lflang"
     $ export AOCL_ROOT="<path to AOCL-BLAS install directory>"
     
     **Using 32-bit Integer (LP64)**
     
     $ cmake ../ -DENABLE_AMD_AOCC_FLAGS=ON -DENABLE_AOCL_BLAS=ON
     -DCMAKE_INSTALL_PREFIX=<your-install-dir> -
     DLIBAOCLUTILS_INCLUDE_PATH=<path_to_libaoclutils_header_files> -D
     LIBAOCLUTILS_LIBRARY_PATH=<path_to_libaoclutils library>
     
     **Using 64-bit Integer (ILP64)**
     
     $ cmake ../ -DENABLE_ILP64=ON -DENABLE_AMD_AOCC_FLAGS=ON
     -DENABLE_AOCL_BLAS=ON -DCMAKE_INSTALL_PREFIX=<your-install-dir>
     -DLIBAOCLUTILS_INCLUDE_PATH=<path_to_libaoclutils_header_files> -D
     LIBAOCLUTILS_LIBRARY_PATH=<path_to_libaoclutils library>
     

   AOCL_ROOT environment variable must have the directories “include” and “lib” containing the necessary header files and binary of AOCL-BLAS respectively. As an alternate to setting environment variable, you can specify root path of the AOCL-BLAS library through the CMake option “AOCL_ROOT”:

   $ cmake -DENABLE_AMD_AOCC_FLAGS=ON -DENABLE_AOCL_BLAS=ON
   -DAOCL_ROOT=<path to AOCL-BLAS install directory> ...
   

   Shared library is turned on by default. To generate static library, provide the additional option:

   -DBUILD_SHARED_LIBS=OFF
   

3. Compile and install the library:

   $ cmake --build . -j
   or
   $ make -j
   

   This will generate libflame.a/libflame.so library in the lib directory.

   To install the library, run:

   $ make install
   

Method 2: Using Autotools (Configure/Makefile)

Explicit linking with AOCL-BLAS library for tighter coupling between AOCL-LAPACK and AOCL-BLAS is not supported via autotools build. Use CMake based build for using this feature as explained above.

1. Set the header file path of AOCL-Utils in CFLAGS environment variable:

   $ export CFLAGS="-I<path to libaoclutils include directory>"
   

2. Run the configure script. An example below shows the recommended options to be used when compiling on AMD “Zen”-based processors.

   • With GCC (default)

     **Using 32-bit Integer (LP64)**
     
     $ ./configure --enable-amd-flags --prefix=<your-install-dir>
     
     **Using 64-bit Integer (ILP64)**
     
     $ ./configure --enable-amd-flags –enable-ilp64
     --prefix=<your-install-dir>
     

   • With AOCC

     $ export CC=clang
     $ export FC=flang
     $ export FLIBS="-lflang"
     
     **Using 32-bit Integer (LP64)**
     
     $ ./configure --enable-amd-aocc-flags --prefix=<your-install-dir>
     
     **Using 64-bit Integer (ILP64)**
     
     $ ./configure --enable-amd-aocc-flags –enable-ilp64
     --prefix=<your-install-dir>
     

3. Make and install using the following commands:

   $ make -j
   $ make install
   

   By default, without the configure option prefix, the library will be installed in $HOME/flame.

For more information on the detailed steps to build and install AOCL-LAPACK including additional configuration options for tests, documentation and more please refer BUILD.md file under source root.

Auto-linking AOCL-Utils Library

The option to merge the AOCL-Utils library with the AOCL-LAPACK library is deprecated and not recommended in most scenarios. This is provided as backward compatibility for previous release.

Auto-linking of AOCL-Utils can be done using “ENABLE_EMBED_AOCLUTILS” option for both CMake and autoconfigure tools build mode. With this option, AOCL-LAPACK automatically links with libaoclutils library by downloading the source of libaoclutils from AMD GitHub, compiling it and linking/merging with AOCL-LAPACK library. A sample command is as follows:

**CMake Build:**

$ cmake ../ -DENABLE_AMD_FLAGS=ON -DENABLE_EMBED_AOCLUTILS=ON

**Autoconfigure:**

$ configure --enable-amd-flags
$ make ENABLE_EMBED_AOCLUTILS=1 -j

With embed AOCL-Utils build, if an external path is provided for the libaoclutils binary and header files through separate flags, ‘LIBAOCLUTILS_LIBRARY_PATH’ and

‘LIBAOCLUTILS_INCLUDE_PATH’ respectively, the specified library is used instead of downloading from GitHub. A sample command is as follows:

**CMake Build:**

$ cmake ../ -DENABLE_AMD_FLAGS=ON -DENABLE_EMBED_AOCLUTILS=ON
DLIBAOCLUTILS_LIBRARY_PATH=<path/to/libaoclutils/library>
-DLIBAOCLUTILS_INCLUDE_PATH=<path/to/libaoclutils/header/files>

**Autoconfigure:**

$ make ENABLE_EMBED_AOCLUTILS=1
LIBAOCLUTILS_LIBRARY_PATH=<path/to/libaoclutils/library>
LIBAOCLUTILS_INCLUDE_PATH=<path/to/libaoclutils/header/files> -j

Additional Notes on Configuration Options

1. By default, the configuration options ENABLE_AMD_FLAGS and ENABLE_AMD_AOCC_FLAGS enable multi-threading using OpenMP for the selected APIs in AOCL-LAPACK. To disable multi- threading, use the configure option ENABLE_MULTITHREADING=OFF.

   Example:

   $ cmake ../ -DENABLE_AMD_FLAGS=ON -D ENABLE_MULTITHREADING=OFF
   

   Similarly, for autotools build, use the flag –enable-multithreading to set multi-threading ON (default) or OFF.

2. To support binary portability across different architectures, the default compiler flags are set to -mtune=native -mavx2 -mfma -O3.

   This requires AVX2 and Fused Multiply Accumulate (FMA) support from the target CPU as mentioned in the Prerequisites section.

   For enabling further optimizations, such as enabling AVX2, FMA, or AVX512 depending on the ISA supported on the target CPU, you can use the following steps:

   Using CMake

   Set the flag LF_ISA_CONFIG to the desired ISA support. The available options are Auto, AVX2 (default), AVX512, and None. The command to use this is as follows:

   $ cmake .. -DLF_ISA_CONFIG=AVX512 -DENABLE_AMD_FLAGS=ON
   

   Using Configure/Makefile

   Set the configure option –enable-optimizations to the desired optimization flags and that will override the default flags. For example, on a AMD “Zen4”-based processor, you can set ‘znver4’ flag for improved performance:

   $ ./configure --enable-amd-flags
   --enable-optimizations="-march=znver4 -O3"
   
   or
   
   $ ./configure --enable-amd-flags
   --enable-optimizations="-march=native -O3"
   

   For the first case, ensure that the compiler you use supports ‘znver4’ flag.

5.1.2. Using Pre-Built Libraries#

You can find the AOCL-LAPACK library binaries for Linux at the following URL. The pre-built AOCL-LAPACK binaries are compiled with ENABLE_AOCL_BLAS option. Hence applications must link with AOCL-BLAS when using prebuilt AOCL-LAPACK library.

https://www.amd.com/en/developer/aocl.html#libflame

Also, the AOCL-LAPACK binary can be installed from the AOCL master installer tar file available at the following URL:

https://www.amd.com/en/developer/aocl.html

The tar file includes pre-built binaries of the other AMD libraries as explained in Using Master Package.

5.2.1. Use by Applications#

To use AOCL-LAPACK in your application, link with AOCL-LAPACK, AOCL-BLAS,and AOCL-Utils libraries while building the application.

AOCL-Utils library has libstdc++ library dependency. As AOCL-LAPACK is dependent on AOCL-Utils, applications must link with libstdc++(-lstdc++) as well.

An example program demonstrating the usage of AOCL-LAPACK is located at libflame/test/ example. This directory contains example source file showing the usage of AOCL-LAPACK library functions.

Use the included CMake script to compile and execute the program. You can test it on both Linux and Windows.

1. Move to installed examples directory:

   $ cd test/example
   

2. Configure the build system:

   $ mkdir build
   $ cd build
   $ cmake .. -DEXT_BLAS_LIBRARY_DEPENDENCY_PATH=< path to blas library>
   - DEXT_LAPACK_LIBRARY_PATH=<path to AOCL-LAPACK library>
   -DEXT_BLAS_LIBNAME=blas_lib_name -
   DEXT_LAPACK_LIBNAME=lapack_lib_name -DEXT_FLAME_HEADER_PATH=<path to
   AOCL-LAPACK header file FLAME.h> -DAOCLUTILS_LIBRARY_PATH=<path to
   aoclutils library>
   

   Example:

   $ cmake .. -DEXT_BLAS_LIBRARY_DEPENDENCY_PATH=/home/user/blis
   -DEXT_LAPACK_LIBRARY_PATH=/home/ user/libflame
   -DEXT_BLAS_LIBNAME=libblis-mt.a -DEXT_LAPACK_LIBNAME=libflame.a -
   DEXT_FLAME_HEADER_PATH=/home/user/aocl/include
   -DAOCLUTILS_LIBRARY_PATH=/home/usr/aoclutils- install/lib
   

3. Compile the sample applications:

   **For Linux**
   
   $ cmake --build . or make
   
   **For Windows**
   
   $ cmake --build .
   

4. Run the application

   **For Linux**
   
   $ ./test_dgetrf.x
   
   **For Windows**
   
   $ cd Debug
   $ test_dgetrf.exe
   

5.3.1. Building AOCL-LAPACK Using GUI#

5.3.2. Building AOCL-LAPACK Using Command-Line Arguments#

The project configuration and build procedures can also be triggered from the command prompt. The corresponding steps are described in the following sections.

$ cmake -S .. -B . Example for building ILP64 mode binaries:
$ cmake -S .. -B . -G "Visual Studio 17 2022"
-DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON -
DEXT_BLAS_LIBNAME="AOCL-LibBlis-Win-MT-dll.lib"
-DCMAKE_EXT_BLAS_LIBRARY_DEPENDENCY_PATH="<path to AOCL-BLAS
library>" -DAOCL_ROOT = <path to AOCL-BLAS install directory having
include and lib folders> -DLIBAOCLUTILS_LIBRARY_PATH=<path to
AOCL-Utils library including library> -
DLIBAOCLUTILS_INCLUDE_PATH=<path to AOCL-Utils header files>
-DENABLE_ILP64=ON - DENABLE_AMD_FLAGS=ON -DENABLE_AOCL_BLAS=ON -TLLVM
-DBUILD_TEST=OFF -DBUILD_NETLIB_TEST=OFF -DENABLE_WRAPPER=ON
-DOpenMP_libomp_LIBRARY="C:\Program Files\LLVM\lib\libomp.lib"

$ cmake --build . --config Release

5.3.3. Building and Running Test Suite#

The Microsoft Visual Studio project for the test suite is generated as a part the CMake generate step. You can build the test projects from the Microsoft Visual Studio GUI or the command prompt as described in the previous sections.

As mentioned in AOCL-LAPACK Config Options, enable “BUILD_TEST” to build a new main test suite of AOCL-LAPACK. To build a legacy test suite, set “BUILD_LEGACY_TEST”.