Understanding CMAKE_FIND_PACKAGE_WARN_NO_MODULE for Explicit Search Modes in CMake

Purpose

• Helps prevent potential issues and promotes clarity in your CMake code.
• Enforces explicit search mode usage in find_package commands.

Behavior

• This encourages developers to be explicit about what they're searching for, making the code more readable and reducing the risk of unexpected behavior due to implicit assumptions.
• When set to TRUE (default in CMake 3.15 and later), find_package issues a warning if you call it without specifying a search mode (e.g., MODULE, CONFIG, or NO_MODULE).

How it Works

• The find_package command typically searches for packages in two main modes:
  • Config Mode (Implicit if not specified)
    Looks for a package configuration file (usually named Find<package>.cmake). This mode is often used for external libraries or frameworks that provide configuration information.
  • Module Mode
    Searches for a specific CMake module within the package's directory structure. This mode might be used for internal project modules or custom CMake modules.

Example

# Without explicit mode (warning will be issued if CMAKE_FIND_PACKAGE_WARN_NO_MODULE is TRUE)
find_package(SomePackage)

# With explicit mode (preferred approach)
find_package(SomePackage REQUIRED MODULE)  # Search for a module
find_package(SomePackage OPTIONAL CONFIG)  # Search for config file (optional)

• If you're using CMake versions before 3.15, consider manually adding the warning or using a custom function to enforce explicit modes.
• Explicitly specifying the search mode provides clarity and avoids ambiguity.
• Setting CMAKE_FIND_PACKAGE_WARN_NO_MODULE to TRUE is generally recommended as it helps catch potential problems early in the development process.

---

Scenario 1: Implicit Mode Warning (Default Behavior)

# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)  # Assuming CMake 3.15 or later

# No explicit search mode (warning will be issued if CMAKE_FIND_PACKAGE_WARN_NO_MODULE is TRUE)
find_package(SomePackage)

if(TARGET SomePackage::SomeTarget)
  # Use SomePackage target
endif()

• This prompts the developer to consider whether they intended to search for a module (MODULE) or a configuration file (CONFIG).
• If CMAKE_FIND_PACKAGE_WARN_NO_MODULE is set to TRUE (default in CMake 3.15 and later), CMake will issue a warning during configuration, indicating that the search mode is not explicit.
• In this case, we call find_package(SomePackage) without specifying a search mode.

Scenario 2: Explicit Search Modes (Preferred Approach)

# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)  # Assuming CMake 3.15 or later

# Explicit MODULE search (assuming SomePackage provides a Find module)
find_package(SomePackage REQUIRED MODULE)  # Search for a module named FindSomePackage.cmake

if(TARGET SomePackage::SomeTarget)
  # Use SomePackage target
endif()

# Optional CONFIG search (for cases where a configuration file might exist)
find_package(SomePackage OPTIONAL CONFIG)  # Search for FindSomePackage.cmake or SomePackageConfig.cmake

• This approach clearly states which search path is being used, enhancing code readability and reducing the risk of unintended behavior.
• Here, we explicitly specify the search modes:
  • find_package(SomePackage REQUIRED MODULE) searches for a module named FindSomePackage.cmake.
  • find_package(SomePackage OPTIONAL CONFIG) optionally searches for FindSomePackage.cmake or SomePackageConfig.cmake.

• You can adjust the search modes (MODULE, CONFIG, or NO_MODULE) based on your project's requirements and whether the specific package provides a Find module or relies on configuration files.
• Scenario 2 showcases explicit search modes, making the code more maintainable.
• Scenario 1 demonstrates the default implicit mode and potential warning.

---

Custom Function

function(find_package_explicit REQUIRED_NAME OPTIONAL_NAME MODE)
  if(NOT MODE)
    message(WARNING "find_package_explicit called without a search mode (MODULE, CONFIG, or NO_MODULE)")
  endif()

  find_package(${REQUIRED_NAME} ${OPTIONAL_NAME} ${MODE})
endfunction()

# Usage
find_package_explicit(SomePackage REQUIRED MODULE)  # Preferred approach

Manual Warning

• Add a comment or message within your CMake code to remind developers about specifying search modes.

Upgrading CMake (if feasible)

• The most robust solution is to upgrade your CMake version to at least 3.15, which has CMAKE_FIND_PACKAGE_WARN_NO_MODULE built-in.

• In cases where you only need to warn for specific packages, manual warnings within the code might suffice. However, this approach can be less centralized and easier to overlook.
• If you're stuck with an older CMake version (pre-3.15) and can't upgrade, creating a custom function is a good option.