Find Modules¶

To streamline finding external tools our build depends on, we provide several Find Modules in our cmake/ directory which are discoverable by the CMake find_package command. Encapsulating code for wrangling dependencies in separate modules makes our CMakeLists.txt files less cluttered and more readable, as the find_package interface forces explicit definition of requirements. Failing to find dependencies can result in portions of our build being disabled, often testing components.

For example, Clang provides many clang based tools as part of a package, but we don’t require them all. Using a FindClangTools Module lets us select only the individual tools we need via the COMPONENTS keyword. The VERSION keyword can also be used to mandate the version of the tools needed, useful when we only support fixed versions as part of our build.

See also

All Find Modules are implemented using FindPackageHandleStandardArgs

FindClangTools Module¶

This find package module searches for clang tools on the system PATH. In order to be future proof, the desired tools are specified using the COMPONENTS keyword and the desired version is specified using the VERSION keyword.

See also

Depends on CAPlatform Module for CA_HOST_EXECUTABLE_SUFFIX.

This module adds the following targets:

ClangTools::${component}: For each specifed component

Variables

This modules adds the following variables:

ClangTools_FOUND¶: Set to TRUE if all components found, FALSE otherwise

ClangTools_${component}_EXECUTABLE¶: Path to the specified component

Usage

# Discovers Version 16 of clang-format & clang-tidy
find_package(ClangTools 16 COMPONENTS clang-format clang-tidy)

FindClspv Module¶

This module finds if clspv is installed and determines where the executable is.

Targets

This module sets the following targets:

clspv: For use in add_custom_{command,target} COMMAND’s

Variables

This module sets the following variables:

Clspv_FOUND¶: Set to TRUE if found, FALSE otherwise

Clspv_EXECUTABLE¶: Path to clspv executable.

Usage

find_package(Clspv)

FindGitClangFormat Module¶

This module finds if git-clang-format is installed and determines where the executable script is, version checks are not supported.

Targets

This module sets the following targets:

git-clang-format: For use in add_custom_{command,target} COMMAND’s

Variables

This module sets the following variables:

GitClangFormat_FOUND¶: Set to TRUE if found, FALSE otherwise

GitClangFormat_EXECUTABLE¶: Path to git-clang-format executable

Usage

find_package(GitClangFormat)

See also

Used to implement the Format Module.

ImportLLVM Module¶

Module imports LLVM into the ComputeAorta build by pulling in LLVM CMake modules from the install directory of a build.

User option CA_LLVM_INSTALL_DIR is required to be set to the filepath of the LLVM install before including this module. The option CA_RUNTIME_COMPILER_ENABLED is also required to be TRUE to use this module, otherwise a LLVM-less offline build is desired.

set(CA_LLVM_INSTALL_DIR "<path/to/install/directory>")
set(CA_RUNTIME_COMPILER_ENABLED TRUE)
include(ImportLLVM)

Using this location we append the directories containing LLVM CMake modules to CMAKE_MODULE_PATH, and import the following LLVM modules:

LLVMConfig for LLVM.
ClangTargets for Clang.

Once the modules are included we verify the LLVM version is supported and set some additional compile definitions.

CA_LLVM_VERSIONS¶: Defines a list of supported LLVM versions, used to verify that LLVM_PACKAGE_VERSION from the imported LLVM install is a supported version.

FindLit Module¶

This module finds if lit is installed and determines where the executable is.

Targets

This module sets the following targets:

lit: For use in add_custom_{command,target} COMMAND’s

Variables

This module sets the following variables:

Lit_FOUND¶: Set to TRUE if found, FALSE otherwise

Lit_EXECUTABLE¶: Path to lit executable

Usage

find_package(Lit)

FindSpirvTools Module¶

This module searches for SPIRV-Tools on the systems PATH or using the VULKAN_SDK environment variable. Multiple components can be specified to search for specific tools provided by SPIRV-Tools.

See also

Depends on CAPlatform Module for CA_HOST_EXECUTABLE_SUFFIX.

Targets

This module adds the following targets:

spirv::${component}: For each specified component

Variables

This module adds the following variables:

SpirvTools_FOUND¶: Set to TRUE if all components are found, FALSE otherwise

SpirvTools_${component}_EXECUTABLE¶: Path to the specifed component

Usage

# Finds the spirv-as standalone assembler
find_package(SpirvTools COMPONENTS spirv-as)

Namespaces¶

Our Find Modules make use of CMake’s double colon namespace prefix when creating component targets, conforming to syntax ‘<package>::<component>’. This is in accordance with policy CMP0028 where CMake will recognize that values passed to target_link_libraries that contain :: in their name are supposed to be Imported Targets rather than just library names, and will produce appropriate diagnostic messages.