From 62c121163d2be65422daa59de9b6c84748c3d8ff Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Wed, 21 May 2025 00:41:47 +0200
Subject: [PATCH] CheckVariableExists: Update documentation

- Added intro code block showing how to include this module.
- Added examples section.
- Added missing CMAKE_REQUIRED_LINK_DIRECTORIES variable (this module
  can also use it as of CMake 3.31).
- Added a note that this is a linker only check and it doesn't check
  whether the variable is also declared in headers, unlike
  check_symbol_exists().
- Added "See Also" section.
---
 Modules/CheckVariableExists.cmake | 83 ++++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 6 deletions(-)

diff --git a/Modules/CheckVariableExists.cmake b/Modules/CheckVariableExists.cmake
index a33b76b92d..62a26fa498 100644
--- a/Modules/CheckVariableExists.cmake
+++ b/Modules/CheckVariableExists.cmake
@@ -5,21 +5,44 @@
 CheckVariableExists
 -------------------
 
-Check if the variable exists.
+This module provides a command to check whether a C variable exists.
+
+Load this module in a CMake project with:
+
+.. code-block:: cmake
+
+  include(CheckVariableExists)
+
+Commands
+^^^^^^^^
+
+This module provides the following command:
 
 .. command:: check_variable_exists
 
+  Checks once if a C variable exists:
+
   .. code-block:: cmake
 
     check_variable_exists(<var> <variable>)
 
-  Check if the variable ``<var>`` exists and store the result in an internal
-  cache variable ``<variable>``.
+  This command attempts to compile and link a test C program that references
+  the specified C variable ``<var>``.  A boolean result of whether
+  the check was successful is stored in an internal cache variable
+  ``<variable>``.
 
-  This macro is only for ``C`` variables.
+  .. note::
 
-The following variables may be set before calling this macro to modify
-the way the check is run:
+    Prefer using :module:`CheckSymbolExists` or :module:`CheckSourceCompiles`
+    instead of this command for more robust detection.  This command performs
+    a link-only check and doesn't detect whether a variable is also declared
+    in system or library headers.  Neither can it detect variables that might
+    be defined as preprocessor macros.
+
+  .. rubric:: Variables Affecting the Check
+
+  The following variables may be set before calling this command to modify
+  the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst
 
@@ -29,8 +52,56 @@ the way the check is run:
 
   .. include:: /module/include/CMAKE_REQUIRED_LIBRARIES.rst
 
+  .. include:: /module/include/CMAKE_REQUIRED_LINK_DIRECTORIES.rst
+
   .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst
 
+Examples
+^^^^^^^^
+
+Example: Basic Usage
+""""""""""""""""""""
+
+In the following example, a check is performed whether the linker sees the
+C variable ``tzname`` and stores the check result in the
+``PROJECT_HAVE_TZNAME`` internal cache variable:
+
+.. code-block:: cmake
+
+  include(CheckVariableExists)
+
+  check_variable_exists(tzname PROJECT_HAVE_TZNAME)
+
+Example: Isolated Check With Linked Libraries
+"""""""""""""""""""""""""""""""""""""""""""""
+
+In the following example, this module is used in combination with the
+:module:`CMakePushCheckState` module to link additional required library
+using the ``CMAKE_REQUIRED_LIBRARIES`` variable.  For example, in a find
+module, to check whether the Net-SNMP library has the
+``usmHMAC192SHA256AuthProtocol`` array:
+
+.. code-block:: cmake
+
+  include(CheckVariableExists)
+  include(CMakePushCheckState)
+
+  find_library(SNMP_LIBRARY NAMES netsnmp)
+
+  if(SNMP_LIBRARY)
+    cmake_push_check_state(RESET)
+
+    set(CMAKE_REQUIRED_LIBRARIES ${SNMP_LIBRARY})
+
+    check_variable_exists(usmHMAC192SHA256AuthProtocol SNMP_HAVE_SHA256)
+
+    cmake_pop_check_state()
+  endif()
+
+See Also
+^^^^^^^^
+
+* The :module:`CheckSymbolExists` module to check whether a C symbol exists.
 #]=======================================================================]
 
 include_guard(GLOBAL)