Refactor internal CMake modules

Modules located in the cmake/modules/PHP directory should ideally be
useful not only in php-src but also in PHP extensions scope. This
separates internal modules that are only used when building php-src.

Additionally, investigated the deprecated/obsolete prehistoric
_REENTRANT and _THREAD_SAFE compile definitions further and added notes
in the comments.

Author: petk

cmake/CMakeLists.txt

@@ -89,9 +89,25 @@ check_pie_supported()
 # Configure build types.
 include(cmake/BuildTypes.cmake)
 
+# Check unused linked libraries on executable and shared/module library targets.
+include(PHP/LinkWhatYouUse)
+
+# Enable C and POSIX extensions. The system extensions configuration will be
+# defined in the configuration header main/php_config.h. The php-src code at the
+# time of writing doesn't include this header in order to utilize them
+# everywhere properly. The main/php_config.h should be the first inclusion
+# before including any system header. Perhaps in php.h file. Until then, the
+# compile definitions also need to be added when compiling and using PHP API.
+# Mainly the _GNU_SOURCE.
+include(PHP/SystemExtensions)
+target_link_libraries(php_config INTERFACE PHP::SystemExtensions)
+
 # Detect C standard library implementation.
 include(PHP/StandardLibrary)
 
+# Define GNU standard installation directories.
+include(GNUInstallDirs)
+
 # Set platform-specific configuration.
 include(cmake/Platform.cmake)
 
@@ -125,8 +141,8 @@ add_subdirectory(scripts)
 # Generate *_arginfo.h headers from *.stub.php sources.
 include(PHP/Stubs)
 
-# Check thread safety.
-include(PHP/ThreadSafety)
+# Configure PHP thread safety.
+include(cmake/ThreadSafety.cmake)
 
 ################################################################################
 # Execute all deferred calls. Calls are additionally sorted with natural
@@ -148,7 +164,7 @@ endblock()
 
 # Rebuild all targets as needed.
 if(NOT PHPSystem_EXECUTABLE)
-  include(PHP/Rebuild)
+  include(cmake/Rebuild.cmake)
 endif()
 
 # Enable testing and configure test settings.
@@ -157,8 +173,8 @@ include(cmake/Testing.cmake)
 # Enable and configure CPack module.
 include(cmake/CPack.cmake)
 
-include(PHP/FeatureSummary)
-php_feature_summary()
+# Print build configuration summary.
+include(cmake/Summary.cmake)
 
 message(
   STATUS

cmake/cmake/modules/PHP/Extensions.cmake renamed to cmake/cmake/Extensions.cmake

@@ -1,49 +1,46 @@
 #[=============================================================================[
-# PHP/Extensions
-
 Configure PHP extensions.
 
-This module is responsible for parsing `CMakeLists.txt` files of PHP extensions
-and sorting extensions based on the dependencies listed in the
-`add_dependencies()`. If an extension has specified dependencies, it ensures
-that all dependencies are automatically enabled. If any of the dependencies are
-built as `SHARED` libraries, the extension must also be built as a `SHARED`
-library.
+This internal module is responsible for parsing CMakeLists.txt files of PHP
+extensions and sorting extensions based on the dependencies listed in the
+add_dependencies(). If an extension has specified dependencies, it ensures that
+all dependencies are automatically enabled. If any of the dependencies are built
+as SHARED libraries, the extension must also be built as a SHARED library.
 
 Dependencies can be specified on top of the CMake's built-in command
-`add_dependencies()`, which builds target dependencies before the target itself.
-This module reads the `add_dependencies()` invocations in extensions
-CMakeLists.txt files and automatically enables and configures them as `SHARED`
+add_dependencies(), which builds target dependencies before the target itself.
+This internal module reads the add_dependencies() invocations in extensions
+CMakeLists.txt files and automatically enables and configures them as SHARED
 depending on the configuration if they haven't been explicitly configured. If it
 fails to configure extension dependencies automatically it will result in a
 fatal error at the end of the configuration phase.
 
 Order of the extensions is then also important in the generated
-`main/internal_functions*.c` files (for the list of `phpext_<extension>_ptr` in
-the `zend_module_entry php_builtin_extensions`). This is the order of how the
-modules are registered into the Zend hash table.
+'main/internal_functions*.c' files (for the list of 'phpext_<extension>_ptr' in
+the 'zend_module_entry php_builtin_extensions'). This is the order of how the
+PHP modules are registered into the Zend hash table.
 
 PHP internal API also provides dependencies handling with the
-`ZEND_MOD_REQUIRED`, `ZEND_MOD_CONFLICTS`, and `ZEND_MOD_OPTIONAL`, which should
+'ZEND_MOD_REQUIRED', 'ZEND_MOD_CONFLICTS', and 'ZEND_MOD_OPTIONAL', which should
 be set in the extension code itself. PHP internally then sorts the extensions
-based on the `ZEND_MOD_REQUIRED` and `ZEND_MOD_OPTIONAL`, so build time sorting
+based on the 'ZEND_MOD_REQUIRED' and 'ZEND_MOD_OPTIONAL', so build time sorting
 shouldn't be taken for granted and is mostly used for php-src builds.
 
-Example why setting dependencies with `ZEND_MOD_REQUIRED` might matter:
+Example why setting dependencies with 'ZEND_MOD_REQUIRED' might matter:
 https://bugs.php.net/53141
 
-## Custom CMake properties
+Custom CMake properties:
 
-* `PHP_EXTENSION`
+* PHP_EXTENSION
 
   Target property that designates that the CMake target is a PHP extension.
 
-* `PHP_ZEND_EXTENSION`
+* 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
+  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.
@@ -52,17 +49,10 @@ https://bugs.php.net/53141
   set_target_properties(php_ext_<extension_name> PROPERTIES PHP_ZEND_EXTENSION TRUE)
   ```
 
-* `PHP_EXTENSION_<extension>_DEPS`
+* PHP_EXTENSION_<extension>_DEPS
 
   Global property with a list of all dependencies of <extension> (name of the
   extension as named in ext directory).
-
-## Usage
-
-```cmake
-# CMakeLists.txt
-include(PHP/Extensions)
-```
 #]=============================================================================]
 
 include_guard(GLOBAL)

cmake/cmake/Platform.cmake

@@ -4,23 +4,6 @@ Platform-specific configuration.
 
 include_guard(GLOBAL)
 
-# Check unused linked libraries on executable and shared/module library targets.
-include(PHP/LinkWhatYouUse)
-
-# Enable C and POSIX extensions.
-include(PHP/SystemExtensions)
-
-# The above system extensions will be defined in the main/php_config.h. The
-# php-src code at the time of writing doesn't include C headers in order to
-# utilize them. The main/php_config.h should be the first inclusion before
-# including any system header. Perhaps in php.h file. Until then, the compile
-# definitions also need to be added when compiling and using PHP API. Mainly the
-# _GNU_SOURCE.
-target_link_libraries(php_config INTERFACE PHP::SystemExtensions)
-
-# Define GNU standard installation directories.
-include(GNUInstallDirs)
-
 # Platform-specific configuration. When cross-compiling, the host and target can
 # be different values with different configurations.
 if(NOT CMAKE_HOST_SYSTEM_NAME EQUAL CMAKE_SYSTEM_NAME)

cmake/cmake/modules/PHP/Rebuild.cmake renamed to cmake/cmake/Rebuild.cmake

@@ -1,22 +1,13 @@
 #[=============================================================================[
-# PHP/Rebuild
-
 Ensure all project targets are rebuilt as needed.
 
-When PHP is not found on the system, the `php_sapi_cli` (alias `PHP::sapi::cli`)
-target is used to generate certain files during development. This can lead to
-cyclic dependencies among targets if custom commands depend on the
-`PHP::sapi::cli` target. While such automatic rebuilding is not considered good
-practice, it ensures that all targets are kept up to date.
+When PHP executable is not found on the system, the 'php_sapi_cli' (aliased
+'PHP::sapi::cli') target is used to generate certain files during development.
+This can lead to cyclic dependencies among targets if custom commands depend on
+the 'PHP::sapi::cli' target. While such automatic rebuilding is not considered
+good practice, it ensures that all targets are kept up to date.
 
 TODO: This works only for a limited set of cases for now and will be refactored.
-
-## Usage
-
-```cmake
-# CMakeLists.txt
-include(PHP/Rebuild)
-```
 #]=============================================================================]
 
 include_guard(GLOBAL)

cmake/cmake/modules/PHP/FeatureSummary.cmake renamed to cmake/cmake/Summary.cmake

@@ -1,40 +1,18 @@
 #[=============================================================================[
-# PHP/FeatureSummary
-
-Print summary of enabled/disabled features.
-
-This is built on top of the CMake's `FeatureSummary` module. It sorts feature
+This is built on top of the CMake's FeatureSummary module. It sorts feature
 summary alphabetically and categorizes enabled features into SAPIs, extensions,
 and other global PHP features. Common misconfiguration issues are summarized
 together with missing required system packages.
 
 See also: https://cmake.org/cmake/help/latest/module/FeatureSummary.html
-
-## Functions
-
-Output PHP configuration summary:
-
-```cmake
-php_feature_summary()
-```
-
-## Usage
-
-```cmake
-# CMakeLists.txt
-
-# Include module and output configuration summary
-include(PHP/FeatureSummary)
-php_feature_summary()
-```
 #]=============================================================================]
 
 include_guard(GLOBAL)
 
 include(FeatureSummary)
 
 # Add new item to the summary preamble with dotted leader.
-function(php_feature_summary_preamble_add_item label value output)
+function(_php_summary_preamble_add_item label value output)
   # Template helper to calculate column width.
   set(template " * <label> .................... : <value>")
   string(REGEX MATCH "^ \\\* ([^ ]+ [.]+)" _ "${template}")
@@ -60,14 +38,14 @@ function(php_feature_summary_preamble_add_item label value output)
 endfunction()
 
 # Get summary preamble.
-function(php_feature_summary_preamble result)
-  php_feature_summary_preamble_add_item(
+function(_php_summary_preamble result)
+  _php_summary_preamble_add_item(
     "${PROJECT_NAME} version"
     "${${PROJECT_NAME}_VERSION}"
     preamble
   )
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "PHP API version"
     "${PHP_API_VERSION}"
     preamble
@@ -77,17 +55,17 @@ function(php_feature_summary_preamble result)
     get_target_property(zendVersion Zend::Zend VERSION)
     get_target_property(zendExtensionApi Zend::Zend ZEND_EXTENSION_API_NO)
     get_target_property(zendModuleApi Zend::Zend ZEND_MODULE_API_NO)
-    php_feature_summary_preamble_add_item(
+    _php_summary_preamble_add_item(
       "Zend Engine version"
       "${zendVersion}"
       preamble
     )
-    php_feature_summary_preamble_add_item(
+    _php_summary_preamble_add_item(
       "Zend extension API number"
       "${zendExtensionApi}"
       preamble
     )
-    php_feature_summary_preamble_add_item(
+    _php_summary_preamble_add_item(
       "Zend module API number"
       "${zendModuleApi}"
       preamble
@@ -117,7 +95,7 @@ function(php_feature_summary_preamble result)
       else()
         string(APPEND compiler "${CMAKE_${language}_COMPILER}")
       endif()
-      php_feature_summary_preamble_add_item(
+      _php_summary_preamble_add_item(
         "${languageLabel} compiler"
         "${compiler}"
         preamble
@@ -139,45 +117,45 @@ function(php_feature_summary_preamble result)
       else()
         string(APPEND linker "${CMAKE_${language}_COMPILER_LINKER}")
       endif()
-      php_feature_summary_preamble_add_item(
+      _php_summary_preamble_add_item(
         "${languageLabel} linker"
         "${linker}"
         preamble
       )
     endif()
   endforeach()
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "Building on (host system)"
     "${CMAKE_HOST_SYSTEM}"
     preamble
   )
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "Host CPU"
     "${CMAKE_HOST_SYSTEM_PROCESSOR}"
     preamble
   )
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "Building for (target system)"
     "${CMAKE_SYSTEM}"
     preamble
   )
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "Target CPU"
     "${CMAKE_SYSTEM_PROCESSOR}"
     preamble
   )
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "CMake version"
     "${CMAKE_VERSION}"
     preamble
   )
 
-  php_feature_summary_preamble_add_item(
+  _php_summary_preamble_add_item(
     "CMake generator"
     "${CMAKE_GENERATOR}"
     preamble
@@ -192,15 +170,15 @@ function(php_feature_summary_preamble result)
     set(buildType "N/A")
   endif()
 
-  php_feature_summary_preamble_add_item("Build type" "${buildType}" preamble)
-  php_feature_summary_preamble_add_item("Install prefix" "${CMAKE_INSTALL_PREFIX}" preamble)
+  _php_summary_preamble_add_item("Build type" "${buildType}" preamble)
+  _php_summary_preamble_add_item("Install prefix" "${CMAKE_INSTALL_PREFIX}" preamble)
 
   set(${result} "${preamble}" PARENT_SCOPE)
 endfunction()
 
 # Output configuration summary.
-function(php_feature_summary)
-  php_feature_summary_preamble(preamble)
+function(_php_summary_print)
+  _php_summary_preamble(preamble)
 
   message(STATUS "")
   message(STATUS "")
@@ -374,3 +352,5 @@ function(php_feature_summary)
     DESCRIPTION "The following REQUIRED packages have not been found:\n"
   )
 endfunction()
+
+_php_summary_print()