Refactor properties and add PHP_THREAD_SAFETY property

- The PHP_EXTENSION_DIR is now determined during the generation phase
  properly, whether the thread safety is enabled by the configuration
  variable or by the apache2handler SAPI automatically.
- Build types refactored with some nits and fixes
- ZEND_DEBUG is now set when the build type is either Debug or
  DebugAssertions and cache variable is now removed in favor of
  generator expressions only as intended by CMake
- Documentation refactored

Author: petk

cmake/cmake/BuildTypes.cmake

@@ -5,45 +5,47 @@ Configure CMake build types.
 include_guard(GLOBAL)
 
 block()
-  if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
-    get_property(isMultiConfig GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
+  get_property(isMultiConfig GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
 
+  # Set default build type for single-config generators.
+  if(NOT isMultiConfig AND NOT CMAKE_BUILD_TYPE)
+    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY VALUE "Debug")
+  endif()
+
+  if(PROJECT_IS_TOP_LEVEL)
     if(isMultiConfig)
       if(NOT "DebugAssertions" IN_LIST CMAKE_CONFIGURATION_TYPES)
         list(APPEND CMAKE_CONFIGURATION_TYPES DebugAssertions)
       endif()
     else()
       set(
         allowedBuildTypes
-        Debug
-        MinSizeRel
-        Release
-        RelWithDebInfo
-        DebugAssertions # Custom build type with debug assertions enabled in
-                        # release mode.
+          Debug           # Debug info, assertions, not optimized.
+          DebugAssertions # Custom PHP debug build type with assertions enabled
+                          # in the release mode. TODO: Adjust the flags.
+          MinSizeRel      # Optimized for size rather than speed.
+          Release         # No debug info, no assertions, optimized.
+          RelWithDebInfo  # Debug info, optimized, no assertions.
       )
 
       set_property(
         CACHE CMAKE_BUILD_TYPE
         PROPERTY STRINGS "${allowedBuildTypes}"
       )
 
-      if(NOT CMAKE_BUILD_TYPE)
-        set(CMAKE_BUILD_TYPE Debug CACHE STRING "" FORCE)
-      elseif(NOT CMAKE_BUILD_TYPE IN_LIST allowedBuildTypes)
+      set_property(
+        CACHE CMAKE_BUILD_TYPE
+        PROPERTY HELPSTRING
+        "Choose the type of build, options are: ${allowedBuildTypes}"
+      )
+
+      if(NOT CMAKE_BUILD_TYPE IN_LIST allowedBuildTypes)
         message(FATAL_ERROR "Unknown build type: ${CMAKE_BUILD_TYPE}")
       endif()
     endif()
   endif()
 endblock()
 
-# TODO: Remove this in favor of generator expressions. Multi configuration
-# generators are otherwise not checked here like this.
-if(CMAKE_BUILD_TYPE MATCHES "^(Debug|DebugAssertions)$")
-  set(PHP_DEBUG TRUE)
-  set(ZEND_DEBUG 1 CACHE INTERNAL "Whether to enable debugging")
-endif()
-
 target_compile_definitions(
   php_configuration
   INTERFACE

cmake/cmake/Configuration.cmake

@@ -217,25 +217,12 @@ block()
 
     if(PHP_LAYOUT STREQUAL "GNU")
       set(extension_dir "${extension_dir}/${zend_module_api_no}")
-
-      # TODO: When apache2handler SAPI enforces the thread safe build (as done
-      # in the Autotools), the PHP_THREAD_SAFETY variable isn't yet available.
-      if(PHP_THREAD_SAFETY)
-        set(extension_dir "${extension_dir}-zts")
-      endif()
-
-      set(extension_dir "${extension_dir}$<IF:$<CONFIG:Debug>,-debug,>")
+      set(extension_dir "${extension_dir}$<$<BOOL:$<TARGET_PROPERTY:php_configuration,PHP_THREAD_SAFETY>>:-zts>")
+      set(extension_dir "${extension_dir}$<IF:$<CONFIG:Debug,DebugAssertions>,-debug,>")
     else()
       set(extension_dir "${extension_dir}/extensions")
-
-      set(extension_dir "${extension_dir}/$<IF:$<CONFIG:Debug>,debug,no-debug>")
-
-      if(PHP_THREAD_SAFETY)
-        set(extension_dir "${extension_dir}-zts")
-      else()
-        set(extension_dir "${extension_dir}-non-zts")
-      endif()
-
+      set(extension_dir "${extension_dir}/$<IF:$<CONFIG:Debug,DebugAssertions>,debug,no-debug>")
+      set(extension_dir "${extension_dir}$<IF:$<BOOL:$<TARGET_PROPERTY:php_configuration,PHP_THREAD_SAFETY>>,-zts,-non-zts>")
       set(extension_dir "${extension_dir}-${zend_module_api_no}")
     endif()
 

cmake/cmake/modules/PHP/Extensions.cmake

@@ -34,11 +34,54 @@ https://bugs.php.net/53141
 TODO: Improve this or simplify the sorting complexities in its entierity. PHP
 dependencies are handled very basically ATM.
 
-Exposed macro:
+## Exposed macro
 
 ```cmake
 php_extensions_add(subdirectory)
 ```
+
+## Custom CMake properties
+
+* `PHP_ALL_EXTENSIONS`
+
+  Global property with a list of all PHP extensions in the ext directory.
+
+* `PHP_ALWAYS_ENABLED_EXTENSIONS`
+
+  This global property contains a list of always enabled PHP extensions which
+  don't need the `HAVE_<extension-name>` preprocessor macros defined in the PHP
+  configuration header and can be considered as part of the core PHP engine.
+
+* `PHP_EXTENSIONS`
+
+  This global property contains a list of all enabled PHP extensions for the
+  current configuration. Extensions are sorted by the directory priority (see
+  `PHP_PRIORITY` property) and extension dependencies (added with CMake command
+  `add_dependencies()`).
+
+* `PHP_PRIORITY`
+
+  This optional directory property controls the order of the PHP extensions
+  added with the `add_subdirectory()`. Directory added with `add_subdirectory()`
+  won't be visible in the configuration phase for the directories added before.
+  Priority number can be used to add the extension subdirectory prior (0..100)
+  or later (\>100) to other extensions. By default extensions are sorted
+  alphabetically and added in between. This enables having extension variables
+  visible in depending extensions.
+
+* `PHP_ZEND_EXTENSION`
+
+  Extensions can utilize this custom target property, which designates the
+  extension as a Zend extension rather than a standard PHP extension. Zend
+  extensions function similarly to regular PHP extensions, but they are loaded
+  using the `zend_extension` INI directive and possess an internally distinct
+  structure with additional hooks. Typically employed for advanced
+  functionalities like debuggers and profilers, Zend extensions offer enhanced
+  capabilities.
+
+  ```cmake
+  set_target_properties(php_<extension_name> PROPERTIES PHP_ZEND_EXTENSION TRUE)
+  ```
 #]=============================================================================]
 
 include_guard(GLOBAL)
@@ -47,42 +90,16 @@ include_guard(GLOBAL)
 # CMake custom properties.
 ################################################################################
 
-define_property(
-  DIRECTORY
-  PROPERTY PHP_PRIORITY
-  BRIEF_DOCS "Controls when to add subdirectory in the configuration phase"
-  FULL_DOCS "This optional property controls the order of the extensions added "
-            "with add_subdirectory(). Directory added with add_subdirectory() "
-            "won't be visible in the configuration phase for the directories "
-            "added before. Priority number can be used to add the extension "
-            "subdirectory prior (0..100) or later (>100) to other extensions. "
-            "By default extensions are sorted alphabetically and added in "
-            "between. This enables having extension variables visible in "
-            "depending extensions."
-)
-
-define_property(
-  TARGET
-  PROPERTY PHP_ZEND_EXTENSION
-  BRIEF_DOCS "Whether the extension target is Zend extension"
-)
-
 define_property(
   GLOBAL
-  PROPERTY PHP_EXTENSIONS
-  BRIEF_DOCS "A list of all enabled extensions"
-  FULL_DOCS "This property contains a list of all enabled extensions for the "
-            "current configuration. Extensions are sorted by the directory "
-            "priority and their dependencies."
+  PROPERTY PHP_ALL_EXTENSIONS
+  BRIEF_DOCS "A list of all extensions in the ext directory"
 )
 
 define_property(
   GLOBAL
   PROPERTY PHP_ALWAYS_ENABLED_EXTENSIONS
   BRIEF_DOCS "A list of always enabled PHP extensions"
-  FULL_DOCS "This property contains a list of always enabled PHP extensions "
-            "which don't need HAVE_<extension-name> symbols and can be "
-            "considered as part of the core PHP engine."
 )
 
 set_property(GLOBAL PROPERTY PHP_ALWAYS_ENABLED_EXTENSIONS
@@ -98,8 +115,20 @@ set_property(GLOBAL PROPERTY PHP_ALWAYS_ENABLED_EXTENSIONS
 
 define_property(
   GLOBAL
-  PROPERTY PHP_ALL_EXTENSIONS
-  BRIEF_DOCS "A list of all extensions in the ext directory"
+  PROPERTY PHP_EXTENSIONS
+  BRIEF_DOCS "A list of all enabled extensions"
+)
+
+define_property(
+  DIRECTORY
+  PROPERTY PHP_PRIORITY
+  BRIEF_DOCS "Controls when to add subdirectory in the configuration phase"
+)
+
+define_property(
+  TARGET
+  PROPERTY PHP_ZEND_EXTENSION
+  BRIEF_DOCS "Whether the extension target is Zend extension"
 )
 
 ################################################################################

cmake/cmake/modules/PHP/PkgConfigGenerator.cmake

@@ -19,9 +19,7 @@ pkgconfig_generate_pc(
   <pc-template-file>
   <pc-file-output>
   TARGET <target>
-  [INSTALL_DESTINATION <path>]
-  [VARIABLES [<variable> <value>] [<variable_2>:BOOL <value_2>...] ...]
-  [SKIP_BOOL_NORMALIZATION]
+  [VARIABLES <variable> <value> ...]
 )
 ```
 
@@ -30,19 +28,16 @@ template.
 
 * `TARGET`
   Name of the target for getting libraries.
-* `INSTALL_DESTINATION`
-  Path to the pkgconfig directory where generated .pc file will be installed to.
-  Usually it is `${CMAKE_INSTALL_LIBDIR}/pkgconfig`. If not provided, .pc file
-  will not be installed.
 * `VARIABLES`
-  Pairs of variable names and values. To pass booleans, append ':BOOL' to the
-  variable name. For example:
+  Pairs of variable names and values. Variable values support generator
+  expressions. For example:
 
   ```cmake
   pkgconfig_generate_pc(
     ...
     VARIABLES
-      variable_name:BOOL "${variable_name}"
+      debug "$<IF:$<CONFIG:Debug>,yes,no>"
+      variable "$<IF:$<BOOL:${VARIABLE}>,yes,no>"
   )
   ```
 
@@ -54,13 +49,6 @@ template.
   The custom PHP specific `$<PHP_EXPAND:path>` generator expression can be used
   in variable values. It is automatically replaced to `<install-prefix>/path`
   if `path` is relative, or to just `path` if `path` is absolute.
-
-* `SKIP_BOOL_NORMALIZATION`
-  CMake booleans have values `yes`, `no`, `true`, `false`, `on`, `off`, `1`,
-  `0`, they can even be case insensitive and so on. By default, all booleans
-  (`var:BOOL`, see above) are normalized to values `yes` or `no`. If this option
-  is given, boolean values are replaced in .pc template with the CMake format
-  instead (they will be replaced to `ON` or `OFF` and similar).
 #]=============================================================================]
 
 include_guard(GLOBAL)
@@ -97,20 +85,6 @@ function(_pkgconfig_parse_variables variables)
     endif()
     list(POP_FRONT variables var value)
 
-    # Normalize boolean values to either "yes" or "no".
-    if(var MATCHES ".*:BOOL$" AND NOT parsed_SKIP_BOOL_NORMALIZATION)
-      if(value)
-        set(value "yes")
-      else()
-        set(value "no")
-      endif()
-    endif()
-
-    # Remove possible :<TYPE> part from the variable name.
-    if(var MATCHES "(.*):BOOL$")
-      set(var ${CMAKE_MATCH_1})
-    endif()
-
     list(APPEND result_variables ${var})
 
     if(value MATCHES [[^\$<PHP_EXPAND:(.*)>.*]])
@@ -169,10 +143,10 @@ function(pkgconfig_generate_pc)
   cmake_parse_arguments(
     PARSE_ARGV
     2
-    parsed                       # prefix
-    "SKIP_BOOL_NORMALIZATION"    # options
-    "TARGET;INSTALL_DESTINATION" # one-value keywords
-    "VARIABLES"                  # multi-value keywords
+    parsed      # prefix
+    ""          # options
+    "TARGET"    # one-value keywords
+    "VARIABLES" # multi-value keywords
   )
 
   if(parsed_UNPARSED_ARGUMENTS)
@@ -271,8 +245,6 @@ function(pkgconfig_generate_pc)
     COMMENT "[PkgConfig] Generating pkg-config ${filename} file"
   )
 
-  cmake_path(GET output FILENAME output_file)
-
   install(CODE "
     block()
       set(result_variables ${result_variables})
@@ -284,17 +256,9 @@ function(pkgconfig_generate_pc)
 
       configure_file(
         ${template}
-        ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/${output_file}
+        ${output}
         @ONLY
       )
     endblock()
   ")
-
-  if(parsed_INSTALL_DESTINATION)
-    install(
-      FILES
-        ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/${output_file}
-      DESTINATION ${parsed_INSTALL_DESTINATION}
-    )
-  endif()
 endfunction()

cmake/cmake/modules/PHP/ThreadSafety.cmake

@@ -1,16 +1,35 @@
 #[=============================================================================[
 Check for thread safety, a.k.a. ZTS (Zend thread safety) build.
 
-Cache variables:
+## Cache variables
 
 * `ZTS`
+
   Whether PHP thread safety is enabled.
+
+## Custom CMake properties
+
+* `PHP_THREAD_SAFETY`
+
+  When thread safety is enabled (either by the configuration variable
+  `PHP_THREAD_SAFETY` or automatically by the `apache2handler` PHP SAPI module),
+  also a custom target property `PHP_THREAD_SAFETY` is added to the
+  `PHP::configuration` target, which can be then used in generator expressions
+  during the generation phase to determine thread safety enabled from the
+  configuration phase. For example, the `PHP_EXTENSION_DIR` configuration
+  variable needs to be set depending on the thread safety.
 #]=============================================================================]
 
 include_guard(GLOBAL)
 
 include(FeatureSummary)
 
+define_property(
+  TARGET
+  PROPERTY PHP_THREAD_SAFETY
+  BRIEF_DOCS "Whether the PHP has thread safety enabled"
+)
+
 function(_php_thread_safety)
   message(CHECK_START "Checking whether to enable thread safety (ZTS)")
 
@@ -49,6 +68,9 @@ function(_php_thread_safety)
   # directly available. For example, some Zend headers.
   target_compile_definitions(php_configuration INTERFACE ZTS)
 
+  # Set custom target property on the PHP configuration target.
+  set_target_properties(php_configuration PROPERTIES PHP_THREAD_SAFETY ON)
+
   # Add compile definitions for POSIX threads conformance.
   # TODO: Recheck these definitions since many of them are deprecated or
   # obsolete in favor of the compiler automatic definitions when using threading