Document mkvk dependencies and add helpful error (#870)

when not found. Fix comments in FindBash.cmake.

BUILDING.md

@@ -15,7 +15,7 @@ KTX consist of the following parts
 - Load test applications (for [OpenGL<sup>®</sup> 3](https://www.khronos.org/opengl), [OpenGLES<sup>®</sup>](https://www.khronos.org/opengles) or [Vulkan<sup>®</sup>](https://www.khronos.org/vulkan))
 - Documentation
 
-Supported platforms (please to through their specific requirements first)
+Supported platforms (please see their specific requirements first)
 
 - [GNU/Linux](#gnulinux)
 - [Apple macOS/iOS](#apple-macosios)
@@ -477,15 +477,58 @@ ctest --test-dir build -R ktxToolTests
 To create and update CTS test cases and about their specific features and usages
 see the [CTS documentation](https://github.com/KhronosGroup/KTX-Software-CTS/blob/main/README.md).
 
+Generated Source Files (project developers only)
+------------
+All but a few project developers can ignore this section. The files discussed here only need to be re-generated when formats are added to Vulkan or errors are discovered. These will be rare occurrences. 
+
+The following files related to the the VkFormat enum are generated from `vulkan_core.h`:
+
+- lib/vkformat_check.c
+- lib/vkformat_enum.h
+- lib/vkformat_list.inl
+- lib/vkformat_str.c
+- lib/vkformat_typesize.c
+- lib/dfd/dfd2vk.inl
+- lib/dfd/vk2dfd.inl
+- interface/java_binding/src/main/java/org/khronos/ktxVkFormat.java
+- interface/python\_binding/pyktx/vk\_format.py
+
+The following files are generated from the mapping database in the KTX-Specification repo by `generate_format_switches.rb`:
+
+- lib/vkFormat2glFormat.inl
+- lib/vkFormat2glInternalFormat.inl
+- lib/vkFormat2glType.inl
+
+All are generated by the `mkvk` target which is only configured if `KTX_GENERATE_VK_FILES` is set to `ON` at the time of CMake configuration. Since this setting is labelled *Advanced* it will not be visible in the CMake GUI unless `Advanced` is set.
+
+Configuring this target adds some dependencies which are discussed below.
+
 Dependencies
 ------------
 
+### awk
+
+Needed if you are [regenerating source files](#generatedsourcefiles(projectdevelopersonly)).
+
+Standard on GNU/Linux and macOS. Available on Windows as part of Git for
+Windows, WSL (Windows Subsystem for Linux) or Cygwin. Note that no CMake
+`AWK_EXECUTABLE` cache variable is used because *awk* is standard on GNU/Linux
+and macOS and on Windows *awk* tends to be available when *bash* is and there
+the *awk* script is invoked via *bash*.
+
+### bash
+
+Needed for the script that creates the version numbers from `git describe` output. Also needed if you are [regenerating source files](#generatedsourcefiles(projectdevelopersonly)).
+
+Standard on GNU/Linux and macOS. Available on Windows as part of Git for
+Windows, WSL (Windows Subsystem for Linux) or Cygwin.
+
 ### SDL
 
 Needed if you want to build the KTX load tests.
 
-On GNU/Linux you need to install `libsdl2-dev` using your package manager. Builds
-of SDL are provided in the KTX Git repo for iOS, macOS and Windows. These
+On GNU/Linux install `libsdl2-dev` using your package manager.
+Builds of SDL are provided in the KTX Git repo for iOS, macOS and Windows. These
 binaries were built from the 2.0.20 tag. For macOS and Windows you can download
 binaries from [libsdl.org](https://www.libsdl.org/download-2.0.php), if you
 prefer.
@@ -547,9 +590,40 @@ building _libktx_.
 
 On GNU/Linux and Windows you need to install an OpenCL SDK and OpenCL driver. Drivers are standard on macOS & iOS and Xcode includes the SDK. On GNU/Linux the SDK can be installed using your package manager. On Windows, the place from which to download the SDK depends on your GPU vendor. In both cases, the GPU driver typically includes an OpenCL driver. 
 
+### Python
+
+*If you are building pyktx*, review the requirements in the [pyktx](interface/python_binding/README.md) README.
 
-{# vim: set ai ts=4 sts=4 sw=2 expandtab textwidth=75:}
+### Perl
 
-### Python
+Needed if you are [regenerating source files](#generatedsourcefiles(projectdevelopersonly)).
+
+On GNU/Linux install `perl` using your package manager. On macOS Perl is still
+included as of macOS Sonoma. In future you may need to install an additional
+package. On Windows, you need a Perl that writes Windows line endings (CRLF).
+Strawberry Perl via Chocolatey is recommended.
+
+```bash
+    choco install strawberryperl
+```
+
+### Ruby
 
-*If you are building pyktx*, review the requirements in the [pyktx](interface/python_binding/README.md) README.
+Needed if you are [regenerating source files](#generatedsourcefiles(projectdevelopersonly)).
+
+Ruby version 3 or later is required. On GNU/Linux install `ruby` using your
+package manager. On macOS install using a package manager such as Brew or with
+[RVM (Ruby Version Manager)](https://rvm.io/rvm/install). Note that Ruby is included in the Xcode command line tools but as of Xcode 15.3 is still version
+2.6.  On Windows use [RubyInstaller](https://rubyinstaller.org/).
+
+### KTX Specification Source
+
+Needed if you are [regenerating source files](#generatedsourcefiles(projectdevelopersonly)).
+
+`git clone https://github.com/KhronosGroup/KTX-Specification` to a peer
+directory of your KTX-Software workarea or set the value of the
+`KTX_SPECIFICATION` CMake cache variable to the location of your specification
+clone.
+
+
+{# vim: set ai ts=4 sts=4 sw=2 expandtab textwidth=75:}

cmake/mkvk.cmake

@@ -7,7 +7,8 @@
 # registry, vk.xml, in the Vulkan-Docs repo.
 
 # NOTE: Since this must be explicitly included by setting an option,
-# require sought packages.
+# require sought packages. However, in order to give an informative
+# error, REQUIRED is not used in the find_* commands.
 #
 # CAUTION: Outputs of custom commands are deleted during a clean
 # operation so these targets result in clean deleting what are normally
@@ -51,7 +52,28 @@ set(vulkan_header "${mkvk_vulkan_include_dir}/vulkan/vulkan_core.h")
 #    set(CYGWIN_INSTALL_PATH "C:\\Program Files\\Git\\usr")
 #endif()
 
-find_package(Perl REQUIRED)
+string(APPEND not_found_error
+    "not found. "
+    "This is only needed by project maintainers when regenerating source files. "
+    "To silence, set KTX_GENERATE_VK_FILES OFF.")
+find_package(Perl QUIET)
+# Painful. Oh for a way to provide custom error messages for failures.
+if(NOT PERL_EXECUTABLE)
+    message(FATAL_ERROR "Perl executable ${not_found_error}")
+endif()
+
+find_package(Ruby 3 QUIET)
+if(NOT Ruby_EXECUTABLE)
+    message(FATAL_ERROR "Ruby v3 executable ${not_found_error}")
+endif()
+
+find_path(KTX_SPECIFICATION
+    NAMES formats.json
+    PATHS ${PROJECT_SOURCE_DIR}/../KTX-Specification
+    NO_DEFAULT_PATH)
+if(NOT KTX_SPECIFICATION)
+    message(FATAL_ERROR "KTX-Specification repo clone ${not_found_error}")
+endif()
 
 list(APPEND mkvkformatfiles_input
     ${vulkan_header}
@@ -139,17 +161,6 @@ add_custom_target(makedfd2vk
     SOURCES ${makedfd2vk_input}
 )
 
-find_program(RUBY_EXECUTABLE
-    NAMES ruby ruby3.1 ruby31 ruby3.0 ruby30
-    # N.B. Must use HINTS. PATHS are searched after default paths.
-    HINTS $ENV{MY_RUBY_HOME}/bin
-    REQUIRED)
-find_path(KTX_SPECIFICATION
-    NAME formats.json
-    PATHS ${PROJECT_SOURCE_DIR}/../KTX-Specification
-    NO_DEFAULT_PATH
-    REQUIRED)
-
 list(APPEND makevk2gl_input
     ${KTX_SPECIFICATION}/generate_format_switches.rb
     ${KTX_SPECIFICATION}/formats.json)

cmake/modules/FindBash.cmake

@@ -62,7 +62,6 @@ NO_SYSTEM_ENVIRONMENT_PATH
 
 if(NOT BASH_EXECUTABLE)
   # Fallback search in default locations
-  # WSL bash did not work in my case :(
   find_program (
       BASH_EXECUTABLE
       bash
@@ -72,8 +71,9 @@ endif()
 mark_as_advanced (BASH_EXECUTABLE)
 
 # ----------------------------------------------------------------------------
-# get version of found BASH executable
+# Get version of found BASH executable.
 if (BASH_EXECUTABLE)
+  # Set LANG to en because match looks for English "version".
   set(ENV{LANG} "en_US.UTF-8")
   execute_process (COMMAND "${BASH_EXECUTABLE}" --version OUTPUT_VARIABLE _BASH_STDOUT ERROR_VARIABLE _BASH_STDERR)
   if (_BASH_STDOUT MATCHES "version ([0-9]+)\\.([0-9]+)\\.([0-9]+)")
@@ -89,7 +89,7 @@ if (BASH_EXECUTABLE)
 endif ()
 
 # ----------------------------------------------------------------------------
-# handle the QUIETLY and REQUIRED arguments and set *_FOUND to TRUE
+# Handle the QUIET and REQUIRED arguments and set *_FOUND to TRUE
 # if all listed variables are found or TRUE
 include (FindPackageHandleStandardArgs)