Handle QUIET dependencies in dependency provider

Improves the cpp-library dependency provider to correctly filter out dependencies from find_package() calls with the QUIET flag if the package was not found, preventing phantom dependencies in generated Config files. Adds a verification function for QUIET dependencies, updates tests to cover these cases, and documents the behavior and best practices in the integration example.

Author: sean-parent

cmake/cpp-library-dependency-provider.cmake

@@ -31,15 +31,21 @@ if(CMAKE_VERSION VERSION_LESS "3.24")
 endif()
 
 # Check if provider is already installed (avoid double-installation)
+# Skip this check in test mode to allow function definitions to be loaded
 get_property(_CPP_LIBRARY_PROVIDER_INSTALLED GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED)
-if(_CPP_LIBRARY_PROVIDER_INSTALLED)
+if(_CPP_LIBRARY_PROVIDER_INSTALLED AND NOT CPP_LIBRARY_TEST_MODE)
     return()
 endif()
 
 # Define all functions BEFORE installing the provider
 # The dependency provider implementation
 # This function is called before every find_package() and FetchContent_MakeAvailable()
 # It tracks dependency information; CMake automatically falls back to default behavior after return
+#
+# QUIET Dependency Handling:
+# When find_package() is called with QUIET, we track it tentatively, then use cmake_language(DEFER)
+# to verify after find_package() completes whether the package was found. If not found, we remove
+# the tracking to prevent phantom dependencies in the generated Config.cmake.
 function(_cpp_library_dependency_provider method)
     if(method STREQUAL "FIND_PACKAGE")
         _cpp_library_track_find_package(${ARGN})
@@ -53,6 +59,7 @@ endfunction()
 
 # Track a find_package() call
 # Records: package name, version, components, and full call syntax
+# For QUIET packages, defers verification until after find_package() completes
 function(_cpp_library_track_find_package package_name)
     # Parse find_package arguments
     set(options QUIET REQUIRED NO_MODULE CONFIG)
@@ -171,6 +178,46 @@ function(_cpp_library_track_find_package package_name)
     endif()
 
     message(DEBUG "cpp-library: Tracked find_package(${package_name}) → find_dependency(${FIND_DEP_CALL})")
+    
+    # For QUIET packages, defer a check to remove the tracking if the package wasn't found
+    # This prevents phantom dependencies from QUIET find_package() calls that fail
+    if(FP_QUIET)
+        cmake_language(DEFER CALL _cpp_library_verify_quiet_dependency "${package_name}")
+    endif()
+endfunction()
+
+# Verify that a QUIET find_package() call actually found the package
+# Called via cmake_language(DEFER) after find_package() completes
+# Removes the tracking if the package wasn't found (prevents phantom dependencies)
+function(_cpp_library_verify_quiet_dependency package_name)
+    # Check if the package was found using various possible _FOUND variable names
+    # CMake allows packages to set <PackageName>_FOUND or <PACKAGENAME>_FOUND
+    set(FOUND FALSE)
+    
+    if(DEFINED ${package_name}_FOUND AND ${package_name}_FOUND)
+        set(FOUND TRUE)
+    else()
+        # Try uppercase version
+        string(TOUPPER "${package_name}" package_upper)
+        if(DEFINED ${package_upper}_FOUND AND ${package_upper}_FOUND)
+            set(FOUND TRUE)
+        endif()
+    endif()
+    
+    # If not found, remove from tracking
+    if(NOT FOUND)
+        # Remove from the tracked dependency
+        set_property(GLOBAL PROPERTY "_CPP_LIBRARY_TRACKED_DEP_${package_name}" "")
+        
+        # Remove from the list of all tracked dependencies
+        get_property(ALL_DEPS GLOBAL PROPERTY _CPP_LIBRARY_ALL_TRACKED_DEPS)
+        list(REMOVE_ITEM ALL_DEPS "${package_name}")
+        set_property(GLOBAL PROPERTY _CPP_LIBRARY_ALL_TRACKED_DEPS "${ALL_DEPS}")
+        
+        message(DEBUG "cpp-library: Removed QUIET dependency ${package_name} (not found)")
+    else()
+        message(DEBUG "cpp-library: Verified QUIET dependency ${package_name} (found)")
+    endif()
 endfunction()
 
 # Track a FetchContent_MakeAvailable() call
@@ -231,13 +278,16 @@ function(_cpp_library_get_all_tracked_deps OUTPUT_VAR)
 endfunction()
 
 # Now install the dependency provider (after all functions are defined)
-set_property(GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED TRUE)
+# Only install if not already marked as installed (allows tests to skip installation)
+if(NOT _CPP_LIBRARY_PROVIDER_INSTALLED)
+    set_property(GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED TRUE)
 
-cmake_language(SET_DEPENDENCY_PROVIDER _cpp_library_dependency_provider
-    SUPPORTED_METHODS 
-        FIND_PACKAGE
-        FETCHCONTENT_MAKEAVAILABLE_SERIAL
-)
+    cmake_language(SET_DEPENDENCY_PROVIDER _cpp_library_dependency_provider
+        SUPPORTED_METHODS 
+            FIND_PACKAGE
+            FETCHCONTENT_MAKEAVAILABLE_SERIAL
+    )
 
-message(STATUS "cpp-library: Dependency tracking enabled")
+    message(STATUS "cpp-library: Dependency tracking enabled")
+endif()
 

tests/install/CMakeLists.txt

@@ -6,9 +6,15 @@
 
 cmake_minimum_required(VERSION 3.20)
 
-# Include the module we're testing
+# Include the modules we're testing
 include(${CMAKE_CURRENT_LIST_DIR}/../../cmake/cpp-library-install.cmake)
 
+# Include dependency provider functions in test mode
+# This loads the function definitions without installing the provider
+set(CPP_LIBRARY_TEST_MODE TRUE)
+set_property(GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED TRUE)
+include(${CMAKE_CURRENT_LIST_DIR}/../../cmake/cpp-library-dependency-provider.cmake)
+
 # Test counter
 set(TEST_COUNT 0)
 set(TEST_PASSED 0)

tests/install/test_dependency_provider.cmake

@@ -131,3 +131,48 @@ mock_target_links(test29_target "MyPkg::MyPkg")
 _cpp_library_generate_dependencies(RESULT test29_target "mylib")
 verify_output("${RESULT}" "find_dependency(MyPkg 1.0.0 CONFIG)" "Test 29")
 
+# Test 30: QUIET dependency that was not found should be removed
+run_test("QUIET dependency not found - should be removed")
+# Simulate provider tracking a QUIET find_package() that failed
+set_property(GLOBAL PROPERTY "_CPP_LIBRARY_TRACKED_DEP_Qt5" "Qt5 5.15 COMPONENTS Core")
+set_property(GLOBAL APPEND PROPERTY _CPP_LIBRARY_ALL_TRACKED_DEPS "Qt5")
+set_property(GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED TRUE)
+# Simulate that Qt5 was NOT found
+set(Qt5_FOUND FALSE)
+# Call the verification function that would normally be deferred
+_cpp_library_verify_quiet_dependency("Qt5")
+# Now try to generate dependencies - Qt5 should NOT appear
+mock_target_links(test30_target "Threads::Threads")
+_cpp_library_generate_dependencies(RESULT test30_target "mylib")
+verify_output("${RESULT}" "find_dependency(Threads)" "Test 30")
+
+# Test 31: QUIET dependency that was found should be kept
+run_test("QUIET dependency found - should be kept")
+# Simulate provider tracking a QUIET find_package() that succeeded
+set_property(GLOBAL PROPERTY "_CPP_LIBRARY_TRACKED_DEP_OpenSSL" "OpenSSL 1.1.1")
+set_property(GLOBAL APPEND PROPERTY _CPP_LIBRARY_ALL_TRACKED_DEPS "OpenSSL")
+set_property(GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED TRUE)
+# Simulate that OpenSSL WAS found
+set(OpenSSL_FOUND TRUE)
+# Call the verification function
+_cpp_library_verify_quiet_dependency("OpenSSL")
+# Now generate dependencies - OpenSSL SHOULD appear
+mock_target_links(test31_target "OpenSSL::SSL")
+_cpp_library_generate_dependencies(RESULT test31_target "mylib")
+verify_output("${RESULT}" "find_dependency(OpenSSL 1.1.1)" "Test 31")
+
+# Test 32: QUIET dependency with uppercase _FOUND variable
+run_test("QUIET dependency with uppercase _FOUND")
+# Simulate provider tracking a QUIET find_package()
+set_property(GLOBAL PROPERTY "_CPP_LIBRARY_TRACKED_DEP_ZLIB" "ZLIB")
+set_property(GLOBAL APPEND PROPERTY _CPP_LIBRARY_ALL_TRACKED_DEPS "ZLIB")
+set_property(GLOBAL PROPERTY _CPP_LIBRARY_PROVIDER_INSTALLED TRUE)
+# Some packages set UPPERCASE_FOUND instead of PackageName_FOUND
+set(ZLIB_FOUND TRUE)
+# Call the verification function
+_cpp_library_verify_quiet_dependency("ZLIB")
+# ZLIB should be kept
+mock_target_links(test32_target "ZLIB::ZLIB")
+_cpp_library_generate_dependencies(RESULT test32_target "mylib")
+verify_output("${RESULT}" "find_dependency(ZLIB)" "Test 32")
+

tests/install/test_integration_example.txt

@@ -73,6 +73,37 @@ If you need to use CMake 3.20-3.23, use an older version of cpp-library that sup
 
 ## Handling Special Cases
 
+### QUIET Dependencies (Conditional/Optional Packages)
+
+When you use `find_package()` with the QUIET flag, cpp-library automatically filters out dependencies that weren't found. This prevents phantom dependencies in your Config file:
+
+```cmake
+# This will only be included in the Config if Qt5 is actually found
+find_package(Qt5 QUIET COMPONENTS Core)
+
+if(Qt5_FOUND)
+    target_link_libraries(my-library INTERFACE Qt5::Core)
+endif()
+```
+
+**Best Practice for Conditional Dependencies:**
+
+```cmake
+# Option 1: Use if() to conditionally search (recommended)
+if(MYLIB_FEATURE_X)
+    find_package(Qt5 COMPONENTS Core)  # Only searched if feature enabled
+    target_link_libraries(my-library INTERFACE Qt5::Core)
+endif()
+
+# Option 2: Use QUIET and check _FOUND (automatic filtering)
+find_package(Qt5 QUIET COMPONENTS Core)
+if(Qt5_FOUND)
+    target_link_libraries(my-library INTERFACE Qt5::Core)
+endif()
+```
+
+Both approaches work correctly with cpp-library's dependency tracking.
+
 ### Non-namespaced Targets
 
 Non-namespaced targets require explicit mapping (both with and without provider):