added optional program discovering and format target functions

Author: codethinki

cth_assertions.cmake

@@ -292,4 +292,32 @@ function(cth_assert_program prog)
     endif()
 
     cth_assert_true(${VAR_NAME} REASON "${ARG_REASON}")
+endfunction()
+
+#[[.rst:
+.. command:: cth_assert_file
+
+   .. code-block:: cmake
+
+      cth_assert_file(<file> [REASON <reason>])
+
+   Asserts that a file exists and is not a directory.
+
+   :param file: Path to the file to check
+   :type file: string
+   :param REASON: Optional error message to display if the assertion fails
+   :type REASON: string
+
+   :post: file exists and is not a directory or configuration terminates with FATAL_ERROR
+#]]
+function(cth_assert_file file)
+    set(oneValueArgs REASON)
+    cmake_parse_arguments(PARSE_ARGV 1 ARG "" "${oneValueArgs}" "")
+
+    if(NOT EXISTS "${file}" OR IS_DIRECTORY "${file}")
+        if(NOT ARG_REASON)
+            set(ARG_REASON "File '${file}' does not exist or is a directory")
+        endif()
+        _cth_assertion_failure("${ARG_REASON}")
+    endif()
 endfunction()

cth_target_utilities.cmake

@@ -349,34 +349,75 @@ endfunction()
 
 
 #[[.rst:
-.. command:: cth_add_clang_format_target
+.. command:: cth_add_opt_clang_format_target
 
    .. code-block:: cmake
 
-      cth_add_clang_format_target(<files...>)
+      cth_add_opt_clang_format_target(<target_name> <files...>)
 
-   Creates a custom target named "format" that runs clang-format on specified files.
+   Optionally creates a custom target that runs clang-format on specified files.
+   Only creates the target if clang-format is available.
 
+   :param target_name: Name of the custom target to create
+   :type target_name: string
    :param files: List of source files to format
    :type files: list of file paths
 
-   :pre: clang-format executable is available in PATH
-   :post: A custom target named "format" is created that formats the specified files in-place
+   :post: A custom target is created if clang-format is found; otherwise no target is created
 
    .. note::
       - The format target uses ``-i`` flag to format files in-place
       - The ``-style=file`` flag means clang-format will look for a .clang-format configuration file
       - Files are formatted relative to CMAKE_SOURCE_DIR
+      - Check if the target exists before depending on it in your build
 
-   .. warning::
-      This function will fail if clang-format is not found in PATH.
+   .. seealso::
+      - ``cth_find_opt_clang_format()`` from cth_tool_utilities to locate clang-format optionally
+
+#]]
+function(cth_add_opt_clang_format_target TARGET_NAME)
+    cth_assert_not_empty(${TARGET_NAME} REASON "add_opt_clang_format_target requires a target name")
+
+    include(cth_tool_utilities)
+    cth_find_opt_clang_format()
+
+    if(NOT CLANG_FORMAT_EXECUTABLE)
+        message(STATUS "clang-format not found, skipping ${TARGET_NAME} target creation")
+        return()
+    endif()
+
+    set(FILES_TO_FORMAT ${ARGN})
+
+    add_custom_target(
+        ${TARGET_NAME}
+        COMMAND ${CLANG_FORMAT_EXECUTABLE} -i -style=file ${FILES_TO_FORMAT}
+        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
+        COMMENT "Formatting all source files with clang-format..."
+        VERBATIM
+    )
+endfunction()
+
+#[[.rst:
+.. command:: cth_add_clang_format_target
+
+   .. code-block:: cmake
+
+      cth_add_clang_format_target(<target_name> <files...>)
+
+   Creates a required custom target that runs clang-format on specified files.
+   Terminates configuration with FATAL_ERROR if clang-format is not found.
+
+   :param target_name: Name of the custom target to create
+   :param files: List of source files to format
+
+   :post: A custom target is created, or configuration terminates with FATAL_ERROR if clang-format not found
 
    **Example usage:**
 
    .. code-block:: cmake
 
-      # Format specific files
       cth_add_clang_format_target(
+          format
           src/main.cpp
           src/utils.cpp
           include/header.hpp
@@ -385,26 +426,14 @@ endfunction()
       # Then run: cmake --build . --target format
 
    .. seealso::
+      - ``cth_add_opt_clang_format_target()`` for optional target creation
       - ``cth_find_clang_format()`` from cth_tool_utilities to locate clang-format
       - Create a .clang-format file in your project root to define formatting style
 
 #]]
 function(cth_add_clang_format_target TARGET_NAME)
-    cth_assert_not_empty(${TARGET_NAME} REASON "add_clang_format_target requires a target name")
-
     include(cth_tool_utilities)
     cth_find_clang_format()
 
-    set(FILES_TO_FORMAT ${ARGN})
-
-    
-
-
-    add_custom_target(
-        ${TARGET_NAME}
-        COMMAND ${CLANG_FORMAT_EXECUTABLE} -i -style=file ${FILES_TO_FORMAT}
-        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
-        COMMENT "Formatting all source files with clang-format..."
-        VERBATIM
-    )
+    cth_add_opt_clang_format_target(${TARGET_NAME} ${ARGN})
 endfunction()

cth_tool_utilities.cmake

@@ -4,11 +4,11 @@
 include(cth_assertions)
 
 #[[.rst:
-.. command:: cth_find_program
+.. command:: cth_find_optional_program
 
    .. code-block:: cmake
 
-      cth_find_program(<out_var> <prog> [args...])
+      cth_find_optional_program(<out_var> <prog> [args...])
 
    Locates an external program and exports its path to the parent scope.
 
@@ -18,12 +18,43 @@ include(cth_assertions)
    :param args: Additional arguments to pass to find_program (e.g., PATHS, HINTS)
    :type args: optional arguments
 
-   :post: <OUT_VAR> variable is set in PARENT_SCOPE with the full path to the program, or configuration terminates with FATAL_ERROR if not found
+   :post: <OUT_VAR> variable is set in PARENT_SCOPE with the full path to the program if found, or an empty string if not found
+
+   .. note::
+      Unlike ``cth_find_program()``, this function does not error if the program is not found.
+      Check if the result variable is empty to determine if the program was found.
+
 #]]
-function(cth_find_program OUT_VAR prog)
+function(cth_find_optional_program OUT_VAR prog)
 
     find_program(${OUT_VAR} "${prog}" ${ARGN})
 
+    set(${OUT_VAR} "${${OUT_VAR}}" PARENT_SCOPE)
+endfunction()
+
+#[[.rst:
+.. command:: cth_find_program
+
+   .. code-block:: cmake
+
+      cth_find_program(<out_var> <prog> [args...])
+
+   Locates a required external program and exports its path to the parent scope.
+   Terminates configuration with FATAL_ERROR if not found.
+
+   :param OUT_VAR variable to export program path to
+   :param prog: Name of the program to find
+   :param args: Additional arguments to pass to find_program
+
+   :post: <OUT_VAR> variable is set in PARENT_SCOPE with the full path to the program, or configuration terminates with FATAL_ERROR if not found
+
+   .. seealso::
+      See ``cth_find_optional_program()`` for a variant that does not error if the program is not found.
+
+#]]
+function(cth_find_program OUT_VAR prog)
+    cth_find_optional_program(${OUT_VAR} "${prog}" ${ARGN})
+    
     cth_assert_true(${OUT_VAR} REASON "Program '${prog}' not found")
 
     set(${OUT_VAR} "${${OUT_VAR}}" PARENT_SCOPE)
@@ -63,31 +94,55 @@ function(cth_enable_build_cache)
 endfunction()
 
 #[[.rst:
-.. command:: cth_find_clang_format
+.. command:: cth_find_opt_clang_format
 
    .. code-block:: cmake
 
-      cth_find_clang_format()
+      cth_find_opt_clang_format()
 
    Locates the clang-format executable and exports its path to the parent scope.
+   Does not error if clang-format is not found.
 
-   :post: CLANG_FORMAT_EXECUTABLE is set in PARENT_SCOPE with the full path to clang-format, or configuration terminates with FATAL_ERROR if not found
+   :post: CLANG_FORMAT_EXECUTABLE is set in PARENT_SCOPE with the full path to clang-format, or an empty string if not found
 
    .. note::
-      The clang-format executable must be available in PATH.
+      Check if CLANG_FORMAT_EXECUTABLE is empty to determine if clang-format was found.
 
-   .. warning::
-      This function will fail with FATAL_ERROR if clang-format is not found.
-      Ensure clang-format is installed and available in your system PATH.
+   .. seealso::
+      Use ``cth_add_clang_format_target()`` from cth_target_utilities to create a format target.
+
+#]]
+function(cth_find_opt_clang_format)
+   cth_find_optional_program(CLANG_FORMAT_EXECUTABLE clang-format)
+   
+   if(CLANG_FORMAT_EXECUTABLE)
+      message(STATUS "Found external clang-format: ${CLANG_FORMAT_EXECUTABLE}")
+   endif()
+
+   set(CLANG_FORMAT_EXECUTABLE ${CLANG_FORMAT_EXECUTABLE} PARENT_SCOPE)
+endfunction()
+
+#[[.rst:
+.. command:: cth_find_clang_format
+
+   .. code-block:: cmake
+
+      cth_find_clang_format()
+
+   Locates a required clang-format executable and exports its path to the parent scope.
+   Terminates configuration with FATAL_ERROR if not found.
+
+   :post: CLANG_FORMAT_EXECUTABLE is set in PARENT_SCOPE with the full path to clang-format, or configuration terminates with FATAL_ERROR
 
    .. seealso::
+      See ``cth_find_opt_clang_format()`` for a variant that does not error if clang-format is not found.
       Use ``cth_add_clang_format_target()`` from cth_target_utilities to create a format target.
 
 #]]
 function(cth_find_clang_format)
-   cth_find_program(CLANG_FORMAT_EXECUTABLE clang-format)
+   cth_find_opt_clang_format()
+   
+   cth_assert_true(CLANG_FORMAT_EXECUTABLE REASON "clang-format not found")
 
-   message(STATUS "Found external clang-format: ${CLANG_FORMAT_EXECUTABLE}")
-
    set(CLANG_FORMAT_EXECUTABLE ${CLANG_FORMAT_EXECUTABLE} PARENT_SCOPE)
 endfunction()

readme.md

@@ -28,6 +28,7 @@ Simple assertions that every language should have:
   - `cth_assert_[_not]_target` — assert a CMake target does (not) exists in the current scope.
   - `cth_assert_[_not]_empty` — assert a string value is (not) empty.
   - `cth_assert_program` — locate an external program (supports `find_program` args) and export `<PROG>_PROGRAM` to the parent scope (fails if not found).
+  - `cth_assert_file` — assert that a particular file exists and is not a directory.
 
 ## cth_target_utilities
 To help you set up targets and dependencies quicker: