AOCL Build-It-Yourself

AOCL offers the capability to compile individual libraries and consolidate them into a unified binary. With the Build-It-Yourself feature, you can choose one or more AOCL libraries and merge them into a single library by configuring the appropriate CMake options. This approach simplifies integration by eliminating dependencies on library linking order and preventing API duplication, ensuring smooth and efficient incorporation of multiple AOCL libraries. This unified binary is assigned a default name: libaocl.so/ libaocl.a for Linux or aocl.dll/ aocl.lib for Windows. The base name (aocl) can be customized with the -DAOCL_SINGLE_LIBRARY_NAME=<name> option.

Note

Build-It-Yourself supports selection of AOCL-BLAS, AOCL-Compression, AOCL-Cryptography, AOCL-Data-Analytics, AOCL-DLP, AOCL-FFTZ, AOCL-LAPACK, AOCL-LibM, AOCL-LibMem, AOCL-OpenRNG, AOCL-Sparse, and AOCL-Utils libraries.

AOCL-ScaLAPACK is also supported, but -- by design it cannot be merged into the single binary -- it is built as a separate library that links against the unified libaocl, rather than being folded into it. See Building AOCL-ScaLAPACK.

• AOCL Build-It-Yourself
  • Table of Contents
  • Project structure
  • Configure Build-It-Yourself
    • Linux Prerequisites
    • Windows Prerequisites
    • Clone the Repository
    • Configure the Build
    • Build the Unified Binary
  • Using CMake Presets
    • Introduction
    • On Linux
      • Single-Thread AOCL
      • Multi-Thread AOCL
    • On Windows
  • Enabling Debug and Trace Logging (DTL)
  • Building AOCL-ScaLAPACK
  • Verifying AOCL Installation
  • AOCL Manifest
  • Testing
  • CMake Variables Reference
    • CMake Options to Select Libraries
    • CMake Options for Library Configuration
    • CMake Options for Debug and Trace Logging (DTL)
    • Passing Library-Specific CMake Options
    • CMake Options for Output Library Naming
    • CMake Options for AMD Architecture-Specific Optimizations
    • CMake Options for Build Performance
    • CMake Options to Set Library Source Path
    • CMake Options to Set GIT Repository and Tag/Branch
  • Build Troubleshooting

The repository is organized as follows:

aocl/
├── CMakeLists.txt      Top-level CMake script that drives the unified build
├── CMakePresets.json   Presets for the supported platforms and compilers
├── LICENSE.txt         Consolidated license
├── NOTICES.txt         Third-party notices
├── README.md           This file
├── cmake/              Target-based build modules (per-component scripts + helpers)
├── presets/            Preset fragments included by CMakePresets.json
└── test/               Test sources and their CMake configuration

build/ and install_package/ are generated at build time (the build tree and the install output, respectively) and are not part of the committed sources.

cmake/ — one build script per component (aocl_blas.cmake, aocl_lapack.cmake, aocl_sparse.cmake, aocl_crypto.cmake, aocl_libm.cmake, aocl_compression.cmake, aocl_da.cmake, aocl_libmem.cmake, aocl_utils.cmake, aocl_fftz.cmake, aocl_openrng.cmake, aocl_dlp.cmake) that builds the component in-tree and folds its object files into the unified library, plus the shared helpers:

• aocl_options.cmake — centralized build-options layer.
• aocl_targets_common.cmake — common target and staging helpers.
• aocl_unified.cmake — assembles the final unified libaocl.
• aocl_gen_def.cmake — generates the Windows export .def file.
• aocl_gen_manifest.cmake — embeds the build manifest into the library.

test/ — built when configured with -DENABLE_TESTS=ON:

• CMakeLists.txt — builds the test executables (registered with CTest).
• test_aocl_symbols.c / test_aocl_symbols.h — C tests for AOCL symbols.
• test_aocl_cpp.cpp — C++ API tests.
• test_aocl_cpp_templates.cpp — C++ template-interface tests for AOCL-DA and AOCL-Sparse.
• mix_libraries.F90 — Fortran interop test exercising the BLAS F77 interface (dgemm, lsame) and the BLIS-native C API (bli_thread_get_num_threads) together, with OpenMP.

This section explains how to configure the CMake options and the procedure to build the unified AOCL binary on both Linux and Windows platforms. Note that the procedure to configure is the same for Windows and Linux. For library specific dependencies and pre-requisites, kindly refer the corresponding sections of the Userguide.

The following sub-sections describe the process:

1. Meeting the prerequisites
2. Cloning the repository
3. Configuring the build options
4. Building the unified binary

The following dependencies must be met for installing AOCL on Linux:

• Git

• Python

• CMake

• GCC and g++

• AOCC

• GNU Make (default generator) or Ninja (required only for the Ninja-based presets)

The following dependencies must be met for building AOCL on Windows:

• LLVM

• CMake

• Microsoft Visual Studio IDE

• Microsoft Visual Studio tools:

  • Python development
  • Desktop development with C++: C++ Clang-Cl for v142 build tool(x64/x86)

• Ninja (required only for the Ninja-based presets, for example aocl-win-ninja-*).

For more information on validated versions of compiler/LLVM, CMake, and Python refer to the Validation Matrix chapter in the AOCL userguide document.

Note

Before configuring, ensure the source for every library you enable -- and for its AOCL dependencies (for example, AOCL-LAPACK requires AOCL-BLAS and AOCL-Utils) -- is available: supplied via the corresponding <LIB>_PATH option, or reachable through its <LIB>_GIT_REPOSITORY. Enabling a library automatically enables its AOCL dependencies, but their sources must still be provided; a source with no <LIB>_PATH is otherwise fetched from its git repository at configure time, which requires network access.

To set up and use Build-It-Yourself, you must clone the repository, configure the build options, and build the unified binary.

Clone the repository:

$ git clone https://github.com/amd/aocl.git
$ cd aocl

There are multiple CMake options you can configure. The following sections explain the CMake options to:

1. Include or exclude individual AOCL libraries (see CMake Options to Select Libraries).

2. Provide the source code for the selected libraries by using one of the following options:

   1. Setting the path of the AOCL libraries source code (see CMake Options to Set Library Source Path)
   2. Setting the GIT repository and tag or branch name (see CMake Options to Set GIT Repository and Tag/Branch)

3. Static or Shared Library:

   1. Shared Library -DBUILD_SHARED_LIBS=ON (default)
   2. Static Library -DBUILD_SHARED_LIBS=OFF

4. Select Data Type (LP64 or ILP64):

   1. LP64 -DENABLE_ILP64=OFF (default)
   2. ILP64 -DENABLE_ILP64=ON

5. Enable or disable threading:

   1. Single threading -DENABLE_MULTITHREADING=OFF (default)
   2. Multithreading -DENABLE_MULTITHREADING=ON

6. Link Desired OpenMP library using -DOpenMP_libomp_LIBRARY=<path to OpenMP library> when, -DENABLE_MULTITHREADING=ON.

7. Optionally set a custom base name for the unified library using -DAOCL_SINGLE_LIBRARY_NAME=<name> (default aocl).

Here is an example of a configuration command:

Linux

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF
-DENABLE_ILP64=OFF -DENABLE_AOCL_BLAS=ON -DENABLE_AOCL_UTILS=ON 
-DENABLE_AOCL_LAPACK=ON -DENABLE_MULTITHREADING=ON -DOpenMP_libomp_LIBRARY=""
-DCMAKE_INSTALL_PREFIX=$PWD/install_package

Windows

$ cmake -S . -B build -G "Visual Studio 17 2022" -DCMAKE_BUILD_TYPE=Release
-DBUILD_SHARED_LIBS=OFF -DENABLE_ILP64=OFF -DENABLE_AOCL_BLAS=ON 
-DENABLE_AOCL_UTILS=ON -DENABLE_AOCL_LAPACK=ON -DENABLE_MULTITHREADING=ON -TClangCl
-DCMAKE_INSTALL_PREFIX=%CD%/install_package -DCMAKE_CONFIGURATION_TYPES=Release

Replace the -G generator with the one matching your installed Visual Studio version (for example, Visual Studio 16 2019).

Use the following command to build the unified binary:

$ cmake --build build --config Release --target install

The AOCL Build-It-Yourself project provides a set of CMake presets to simplify the configuration and build process for different platforms and compilers. Some of these presets are:

1. aocl-linux-make-lp-ga-gcc-config: Linux with GNU Make and GCC
2. aocl-linux-make-ilp-ga-gcc-config: Linux with GNU Make and GCC (ILP64)
3. aocl-linux-make-lp-ga-aocc-config: Linux with GNU Make and AOCC
4. aocl-linux-make-ilp-ga-aocc-config: Linux with GNU Make and AOCC (ILP64)
5. aocl-win-msvc-lp-ga-config: Windows with Visual Studio and Clang/LLVM
6. aocl-win-msvc-ilp-ga-config: Windows with Visual Studio and Clang/LLVM (ILP64)
7. aocl-win-ninja-lp-ga-config: Windows with Ninja and Clang/LLVM
8. aocl-win-ninja-ilp-ga-config: Windows with Ninja and Clang/LLVM (ILP64)

Details of aocl-linux-make-lp-ga-gcc-config are given here.

The aocl-linux-make-lp-ga-gcc-config preset is a convenient and efficient way to build AOCL on Linux platforms with GCC. It provides a stable, production-ready configuration while allowing flexibility for customization based on specific requirements.

• How is the Name Derived?

  • aocl: Refers to AMD Optimized Libraries.
  • linux: Indicates that the preset is for Linux platforms.
  • make: Specifies the use of the GNU Make build system.
  • lp: Refers to the LP64 data model, which is the default for most Linux systems.
  • ga: Stands for General Availability Release, indicating that this preset is stable and production-ready.
  • gcc: Specifies the use of the GCC compiler.

• Default Configuration: By default, this preset builds a shared multithreaded library. It can be customized to build static or single-threaded libraries by modifying the relevant CMake variables.

  • CMAKE_BUILD_TYPE: Release (default) Specifies that the build is optimized for performance.
  • BUILD_SHARED_LIBS: ON Indicates that shared libraries are built by default.
  • ENABLE_ILP64: OFF Configures the build to use the LP64 data model.
  • ENABLE_MULTITHREADING: ON Enables multithreading support by default.
  • CMAKE_C_COMPILER: gcc Specifies GCC as the C compiler.
  • CMAKE_CXX_COMPILER: g++ Specifies G++ as the C++ compiler.
  • CMAKE_Fortran_COMPILER: gfortran Specifies GFortran as the Fortran compiler.

• Required Environment Variables: For library-specific environment variables (OpenSSL, Boost, oneAPI, ...), refer to the corresponding library sections of the Userguide.

• Example Command to Use This Preset: To configure the build using this preset, run the following command:

  $ cmake --preset aocl-linux-make-lp-ga-gcc-config --fresh

  This command will set up the build environment with the predefined configuration for this preset.

• Customization Options: You can customize the build by overriding the default CMake variables. For example:

  • To build a static library, set -DBUILD_SHARED_LIBS=OFF.
  • To disable multithreading, set -DENABLE_MULTITHREADING=OFF.

  For more customization options, refer to Configure the Build.

The following sections provide examples of configuration and build commands on Linux using the CMake build system.

Note

Use the -DOpenMP_libomp_LIBRARY option to link the desired OpenMP library.

Complete the following steps to build and install a single-thread AOCL:

1. Configure the library as required:

   # CMake commands
   
   # GCC (Default) and LP64 
   $ cmake --preset aocl-linux-make-lp-ga-gcc-config -DENABLE_MULTITHREADING=OFF --fresh 
   
   # GCC and ILP64
   $ cmake --preset aocl-linux-make-ilp-ga-gcc-config -DENABLE_MULTITHREADING=OFF --fresh 
   
   # AOCC and LP64 
   $ cmake --preset aocl-linux-make-lp-ga-aocc-config -DENABLE_MULTITHREADING=OFF --fresh 
   
   # AOCC and ILP64
   $ cmake --preset aocl-linux-make-ilp-ga-aocc-config -DENABLE_MULTITHREADING=OFF --fresh 

2. Build the unified binary and install using the command:

   $ cmake --build build --config Release -j --target install

Complete the following steps to install a multi-thread AOCL:

1. Configure the library as required:

   # CMake commands
   
   # GCC (Default) and LP64 
   $ cmake --preset aocl-linux-make-lp-ga-gcc-config --fresh 
   
   # GCC and ILP64
   $ cmake --preset aocl-linux-make-ilp-ga-gcc-config --fresh 
   
   # AOCC and LP64 
   $ cmake --preset aocl-linux-make-lp-ga-aocc-config --fresh 
   
   # AOCC and ILP64
   $ cmake --preset aocl-linux-make-ilp-ga-aocc-config --fresh 
   
   # GCC (Default) and LP64 with Desired OpenMP library Path
   $ cmake --preset aocl-linux-make-lp-ga-gcc-config --fresh -DOpenMP_libomp_LIBRARY=<path to OpenMP library>

2. Build the unified binary and install using the command:

   $ cmake --build build --config Release -j --target install

Configure the Project in Command Prompt

# CMake commands using Microsoft Visual Studio Generator
"<Path to Visual Studio Auxiliary>\\Build\\vcvarsall.bat"  x64

# Clang/LLVM (Default) and LP64 
$ cmake --preset aocl-win-msvc-lp-ga-config --fresh 

# Clang/LLVM and ILP64
$ cmake --preset aocl-win-msvc-ilp-ga-config --fresh 

# Clang/LLVM (Default) and LP64 with Desired OpenMP library Path
$ cmake --preset aocl-win-msvc-lp-ga-config --fresh -DOpenMP_libomp_LIBRARY=<path to OpenMP library>

# CMake commands using Ninja Generator

$ "<Path to Visual Studio Auxiliary>\\Build\\vcvarsall.bat"  x64
$ set PATH="<Path to Visual Studio Ninja>";%PATH%

# Clang/LLVM (Default) and LP64 
$ cmake --preset aocl-win-ninja-lp-ga-config --fresh 

# Clang/LLVM and ILP64
$ cmake --preset aocl-win-ninja-ilp-ga-config --fresh 

# Clang/LLVM (Default) and LP64 with Desired OpenMP library Path
$ cmake --preset aocl-win-ninja-lp-ga-config --fresh -DOpenMP_libomp_LIBRARY=<path to OpenMP library>

Build the Project in Command Prompt

$ cmake --build build --config Release --target install

The AOCL components ship a common Debug and Trace Logging (DTL) facility that, when enabled at build time, emits API trace and/or input-log files at runtime (for example an aocldtl_trace.txt trace file in the working directory). DTL is off by default so production builds carry no logging overhead; enable it only when you need to capture the call flow or inputs for debugging.

DTL trace/log modes are consumed by AOCL-BLAS and AOCL-LAPACK; AOCL-Crypto additionally honours the resolved on/off state to toggle its own debug logging (ALCP_ENABLE_DEBUG_LOGGING). The remaining components ignore DTL.

DTL is controlled at configure time with two knobs:

• Global switch -- turn DTL on for the DTL-capable components (AOCL-BLAS, AOCL-LAPACK, and AOCL-Crypto's debug logging) at once:

  # Linux
  $ cmake --preset aocl-linux-make-lp-ga-gcc-config -DENABLE_AOCL_DTL=on --fresh

  :: Windows
  $ cmake --preset aocl-win-msvc-lp-ga-config -DENABLE_AOCL_DTL=on --fresh

  -DENABLE_AOCL_DTL accepts off (default), on/all (both the API trace and the input log), trace (trace stream only) or log (input logging only). The values are case-insensitive (for example ALL, Trace and off are all valid).

• Per-component override -- enable, disable or pick a DTL sub-mode for a single component, independent of the global default, with -DENABLE_AOCL_<COMPONENT>_DTL=<value> where <value> is inherit (default -- follow ENABLE_AOCL_DTL), off, on/all, trace or log. <COMPONENT> is BLAS or LAPACK. For example, to keep DTL off globally but capture only the input log for AOCL-LAPACK and full trace+log for AOCL-BLAS:

  $ cmake --preset aocl-linux-make-lp-ga-gcc-config \
      -DENABLE_AOCL_BLAS_DTL=all -DENABLE_AOCL_LAPACK_DTL=log --fresh

See also CMake Options for Debug and Trace Logging (DTL) in the variables reference.

By design, AOCL-ScaLAPACK is not merged into the single libaocl binary like the other components. Instead, when -DENABLE_AOCL_SCALAPACK=ON is set, Build-It-Yourself first builds the unified libaocl and then builds AOCL-ScaLAPACK as a separate library (libscalapack.so/libscalapack.a on Linux, scalapack.dll/scalapack.lib on Windows) that links against that unified libaocl.

Why it is kept separate (not merged)

• AOCL-ScaLAPACK and AOCL-LAPACK have overlapping functionality: AOCL-ScaLAPACK carries its own copies of a number of LAPACK-named routines (for example the auxiliary and test-matrix generators under its TOOLS/LAPACK tree). Merging AOCL-ScaLAPACK's objects into the same unified libaocl -- which already contains AOCL-LAPACK (libflame) -- would produce duplicate, conflicting symbols, precisely the API duplication the single library is meant to prevent. Building AOCL-ScaLAPACK as a separate library that links libaocl keeps those symbols out of the unified binary while still resolving the shared BLAS/LAPACK routines from it.
• As a consequence of linking libaocl, AOCL-ScaLAPACK can only be built after the unified library exists (its prerequisites AOCL-BLAS, AOCL-Utils, and AOCL-LAPACK live inside libaocl). Its own CMake also runs a configure-time link check against the BLAS/LAPACK it is handed and silently downloads reference BLAS/LAPACK if that fails; since libaocl is not available until the build phase, AOCL-ScaLAPACK is configured and built as an external step (after libaocl), where the check resolves against the real libaocl.

What enabling it does

• Enabling AOCL-ScaLAPACK auto-enables AOCL-LAPACK (which itself pulls in AOCL-BLAS and AOCL-Utils), so its prerequisites are present inside libaocl; you do not have to enable them by hand.
• The AOCL-ScaLAPACK library is installed into the same install_package/lib/ directory as the unified libaocl, so both sit side by side. AOCL-ScaLAPACK ships no public headers, so nothing is added to install_package/include/.

Prerequisites

• An MPI installation (AOCL-ScaLAPACK is an MPI library and configuration fails without one). Point at it with -DMPI_BASE_DIR=<path>, or have a system MPI on the default search paths.
• A Fortran compiler (Linux: gfortran; Windows: ifx/ifort).

Source

Like the other components, the AOCL-ScaLAPACK source is taken from a local path if given, otherwise cloned from git:

• -DSCALAPACK_PATH=<parent dir containing 'aocl-scalapack'> -- use a local copy, or
• -DSCALAPACK_GIT_REPOSITORY=<url> / -DSCALAPACK_GIT_TAG=<tag/branch> -- clone (defaults: https://github.com/amd/aocl-scalapack.git @ master).

Example (Linux)

$ cmake --preset aocl-linux-make-lp-ga-gcc-config \
    -DENABLE_AOCL_SCALAPACK=ON \
    -DMPI_BASE_DIR=/opt/intel/oneapi/mpi/latest --fresh
$ cmake --build build --config Release --target install -j

Example (Windows)

$ cmake --preset aocl-win-msvc-lp-ga-config ^
    -DENABLE_AOCL_SCALAPACK=ON ^
    -DMPI_BASE_DIR="C:/Program Files (x86)/Intel/oneAPI/mpi/latest" --fresh
$ cmake --build build --config Release --target install

After installation, install_package/lib/ contains the unified libaocl alongside the AOCL-ScaLAPACK library.

The AOCL package will be installed in the install_package directory which is created inside the AOCL source directory.

There are two subfolders within the install_package folder: lib and include.

• The include folder contains the header files required for using the AOCL libraries in applications.
• The lib folder contains the compiled binaries:
  • On Linux: libaocl.so and libaocl.a.
  • On Windows: aocl.dll and aocl.lib.

If a custom -DAOCL_SINGLE_LIBRARY_NAME was set, the binaries are named accordingly.

Every unified AOCL binary is self-describing: the build generates a small manifest that records exactly how the library was configured and which component versions it contains. The manifest is:

• Embedded directly into the unified library — on Linux/ELF it lives in a dedicated .aocl_manifest section of libaocl.so and libaocl.a; on Windows it is embedded inside aocl.dll / aocl.lib and is discoverable as printable strings. An accessor const char *aocl_get_manifest(void); is exported so it can also be read at runtime.
• Shipped as a plain-text sidecar at install_package/lib/aocl_manifest.txt, which is the easiest way to inspect it without any tooling.

The manifest is delimited by AOCL-MANIFEST-BEGIN / AOCL-MANIFEST-END and contains the following fields:

The most portable option is simply to read the installed text sidecar:

cat install_package/lib/aocl_manifest.txt          # Linux
type install_package\lib\aocl_manifest.txt         # Windows

To read the manifest directly out of a binary:

On Linux — dump the dedicated ELF section with readelf (works for the shared library):

readelf -p .aocl_manifest install_package/lib/libaocl.so

For the static archive (or as a generic fallback that works for both), extract the manifest block with strings:

strings -n 4 install_package/lib/libaocl.a | grep -A60 AOCL-MANIFEST-BEGIN

On Windows — the manifest is stored as printable strings inside the binary, so extract it with llvm-strings and filter for the manifest fields with findstr (each manifest field is emitted on its own line):

"C:\Program Files\LLVM\bin\llvm-strings.exe" -n 4 "install_package\lib\aocl.dll" ^
  | findstr /b /c:"AOCL-MANIFEST" /c:"library:" /c:"build_date:" /c:"linkage:" ^
    /c:"integer_size:" /c:"threading:" /c:"threading_library:" /c:"architecture:" ^
    /c:"build_type:" /c:"compiler:" /c:"component_count:" ^
    /c:"  - name:" /c:"    version:"

The AOCL Build-It-Yourself project includes comprehensive test executables to validate library functionality. Tests can be enabled by setting -DENABLE_TESTS=ON during CMake configuration.

Build with Tests:

cmake --preset aocl-linux-make-lp-ga-gcc-config \
  -DENABLE_TESTS=ON

cd build
cmake --build . --target install -j 10
cmake --build . --target test_symbols -j 10
./test/test_symbols

Test Coverage:

• Test functions covering 10 AOCL libraries
• Tests include: BLAS, LAPACK, Sparse, LibM, Crypto, Compression, Data Analytics, LibMem, Utils, OpenRNG
• Validates library functionality and API correctness

Test executables: In addition to the C symbol test (test_symbols), the suite builds C++ API tests (test_cpp_symbols, from test_aocl_cpp.cpp) and C++ template-interface tests (test_cpp_templates, from test_aocl_cpp_templates.cpp) when the relevant libraries are enabled, plus a Fortran mixed-library test (mix_libraries). All tests are registered with CTest, so running ctest from the build directory executes the full suite.

This section provides a detailed reference for the CMake variables used to configure the Build-It-Yourself AOCL project. These variables allow customization of the build process, including selecting libraries and specifying source paths. Use these options to tailor the unified AOCL binary to specific requirements.

The following table lists the CMake variables used to include or exclude individual AOCL libraries.

The following table lists additional CMake variables used to configure how selected AOCL libraries integrate and interact with each other.

The following table lists the CMake variables that control the AOCL Debug and Trace Logging (DTL) facility. DTL is disabled by default. For usage examples, see Enabling Debug and Trace Logging (DTL).

Because Build-It-Yourself compiles each selected library in-tree (via FetchContent + add_subdirectory), a library's own CMake options can be set directly on the top-level cmake command with -D<OPTION>=<value> -- the option is inherited by that library's build, with no separate per-library configure step. This is a key convenience of the target-based design. Library behaviour is controlled two ways:

• BIY-exposed options map a common library setting onto a top-level option so it is applied consistently across the merged library. For example:

  • -DENABLE_CBLAS=OFF -- disable the AOCL-BLAS CBLAS interface.
  • -DENABLE_AMD_FLAGS=ON -- enable the AMD-specific flags for the AOCL-LAPACK build.
  • -DENABLE_BLAS_EXT_GEMMT=OFF -- toggle the AOCL-LAPACK external GEMMT path.

• Direct pass-through of any other option a library defines. For example:

  • -DENABLE_AOCL_DYNAMIC=OFF -- disable AOCL-BLAS dynamic thread selection.

Notes:

• A small set of options is forced by BIY to keep the merged library self-consistent and cannot be overridden per library; use the corresponding unified knob instead: linkage (-DBUILD_SHARED_LIBS), integer size (-DENABLE_ILP64), threading (-DENABLE_MULTITHREADING), and architecture (-DAMD_CONFIG).
• Option names are global to a configure: a bare -D<OPTION> applies to every enabled library that defines it (for example, -DENABLE_ASAN=ON affects all libraries that read it).
• For the complete set of options a library supports, refer to that library's section in the AOCL Userguide.

The following table lists the CMake variable used to set the name of the unified AOCL library.

The following table lists the CMake variable used to enable ISA-specific optimizations for AMD processors.

AMD_CONFIG Impact on Libraries:

• AOCL-BLAS (BLIS): Maps directly to BLIS_CONFIG_FAMILY configuration.
• AOCL-LAPACK (LibFlame):
  • zen, zen2, zen3 → AVX2-STRICT optimizations
  • zen4, zen5, zen6 → AVX512-STRICT optimizations
  • Default: AVX2
• AOCL-LibM:
  • zen → Static dispatch with AVX2
  • zen2 → Static dispatch with ZEN2
  • zen3 → Static dispatch with ZEN3
  • zen4 → Static dispatch with ZEN4
  • zen5 → Static dispatch with ZEN5
  • zen6 → Static dispatch with ZEN6
  • Default: Dynamic dispatch (runtime detection)
• AOCL-DA:
  • zen, zen2 → znver2
  • zen3 → znver3
  • zen4 → znver4
  • zen5 → znver5
  • zen6 → znver6
  • amdzen → dynamic
  • Default: dynamic
• AOCL-Sparse:
  • zen, zen2, zen3 → OFF (AVX512 code paths disabled at build time)
  • zen4, zen5, zen6, amdzen → ON (AVX512 code paths enabled at build time)
  • Default: ON
  • Runtime dispatch remains automatic and can be guided using AOCL_ENABLE_INSTRUCTIONS
• AOCL-Compression (AOCL_MAX_ISA_LEVEL, UNIX only — ignored on Windows):
  • zen, zen2, zen3 → AVX2
  • zen4, zen5, zen6, amdzen → AVX512
  • Default: AVX512
• AOCL-FFTZ (ENABLE_INSTRUCTIONS_UPTO):
  • zen, zen2, zen3 → AVX256
  • zen4, zen5, zen6, amdzen → AVX512
  • Default: AVX512
• AOCL-LibMem (ALMEM_ARCH, UNIX/x86 only):
  • zen → zen1; zen2…zen6 → zen2…zen6 (forces that micro-architecture and disables LibMem's own dynamic dispatch)
  • amdzen / unset → auto-detect (dynamic dispatch)

Note: AOCL-Utils, AOCL-Crypto, OpenRNG, AOCL-DLP and AOCL-ScaLAPACK do not expose a compile-time architecture switch (they auto-detect / dispatch at runtime), so AMD_CONFIG does not change how they are built.

# Build with Zen 4 optimizations (AVX512 for LAPACK and LibM)
$ cmake --preset aocl-linux-make-lp-ga-gcc-config -DAMD_CONFIG=zen4 --fresh

# Build with Zen 2 optimizations (AVX2 for LAPACK, static dispatch for LibM)
$ cmake --preset aocl-linux-make-lp-ga-gcc-config -DAMD_CONFIG=zen2 --fresh

# Build with generic AMD optimizations (dynamic dispatch)
$ cmake --preset aocl-linux-make-lp-ga-gcc-config -DAMD_CONFIG=amdzen --fresh

The unified AOCL build compiles every enabled component in-tree (via FetchContent + add_subdirectory), so build parallelism is controlled by the standard CMake build-tool options rather than a project-specific variable. Pass -j / --parallel (optionally with a core count) to cmake --build:

# Use all available cores (best on machines with enough RAM per core)
$ cmake --build build --config Release --target install -j

# Cap the job count on memory-constrained machines (see the note below)
$ cmake --build build --config Release --target install -j <N>

Note: Build parallelism is limited by available memory, not by core count. On high-core-count machines (for example, 96- or 128-core servers) with ample RAM, use all cores (-j) for the fastest build -- dropping to a small fixed number such as -j 8 would leave most of the machine idle. The large translation units in AOCL-BLAS/LAPACK/DA only cause trouble when the number of concurrent jobs outpaces available RAM, so keep the job count at roughly min(cores, free_GB / 2). See Out-of-memory (OOM) during a fully parallel build for a ready-to-use command that computes a memory-safe job count.

The following table lists CMake variables to specify the path of AOCL library sources. These variables are useful when local copies of the repositories are available, particularly in environments without internet access.

The following table lists CMake variables to specify the GIT repository and tag or branch name for cloning individual AOCL libraries. If the source code path is not provided, CMake uses the specified GIT repository and tag or branch. This is useful for building source code from the dev branch of individual libraries. If neither the source code path nor the GIT repository and tag are provided, CMake defaults to the repository and branch/tag for the AOCL stable public release.

Building with unbounded parallelism -- cmake --build build -j (with no job count) or make -j -- starts one compile job per available CPU core. Some AOCL components (notably AOCL-BLAS/BLIS, AOCL-LAPACK/libflame, and AOCL-Data-Analytics) contain large translation units with high peak compiler memory, so on machines with many cores relative to RAM the build can exhaust memory and fail with an out-of-memory (OOM) error -- for example, the compiler is "Killed" (signal 9) or the Linux OOM killer terminates cc1plus / clang.

Workaround: the limiting resource is memory, not cores -- so rather than dropping to a small fixed number like -j 8 (which would badly under-utilize a 96- or 128-core server), size the job count to the machine and cap it only when RAM is the bottleneck. A practical rule of thumb is:

jobs = min(number_of_cores, free_RAM_GB / 2)

That is, allow roughly one compile job per ~2 GB of available RAM, but never more than the core count. For example:

On Linux you can compute and apply a memory-safe job count automatically:

cores=$(nproc)
memgb=$(awk '/MemAvailable/{printf "%d", $2/1048576}' /proc/meminfo)
jobs=$(( memgb/2 < cores ? memgb/2 : cores )); (( jobs < 1 )) && jobs=1
echo "Building with -j $jobs (cores=$cores, MemAvailable=${memgb} GB)"
cmake --build build --config Release --target install -j "$jobs"

Only lower the count further (for example -j 4, -j 2, or -j 1 in the worst case) if the build still hits OOM under heavy memory pressure. See also CMake Options for Build Performance.

On the Visual Studio (multi-config) generator the project configures only the Release configuration. If the build is invoked without selecting it -- cmake --build build with no --config -- MSBuild falls back to its own default, Debug, which does not exist, and fails:

error MSB8013: This project doesn't contain the Configuration and Platform combination of Debug|x64.

Workaround: pass --config Release when building with the Visual Studio generator (the provided presets and the documented build commands already do this):

cmake --build build --config Release

Building Debug binaries: the project defaults to Release and mirrors the available configuration(s) to CMAKE_BUILD_TYPE. To build Debug, set -DCMAKE_BUILD_TYPE=Debug at configure time.

• Single-config generators (Ninja, Unix Makefiles):

  cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
  cmake --build build

• Multi-config generators (Visual Studio): the Debug configuration then becomes available, so build it with --config Debug:

  cmake -S . -B build -G "Visual Studio 17 2022" -T ClangCl -DCMAKE_BUILD_TYPE=Debug
  cmake --build build --config Debug