Update docs and fix CS

Author: petk

cmake/ext/opcache/CMakeLists.txt

@@ -1,7 +1,6 @@
 include(CheckSymbolExists)
 include(CMakeDependentOption)
 include(FeatureSummary)
-include(PHP/CheckCompilerFlag)
 include(PHP/SearchLibraries)
 
 option(EXT_OPCACHE "Enable the opcache extension" ON)

docs/cmake-modules/PHP/ConfigureFile.md

@@ -23,13 +23,10 @@ php_configure_file(
 
 * `VARIABLES`
 
-  Pairs of variable names and values.
+  Pairs of variable names and values. Variable values support generator
+  expressions.
 
   The `$<INSTALL_PREFIX>` generator expression can be used in variable values,
   which is replaced with installation prefix either set via the
   `CMAKE_INSTALL_PREFIX` variable at the configuration phase, or the `--prefix`
   option at the `cmake --install` phase.
-
-  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.

docs/cmake-modules/PHP/Install.md

@@ -0,0 +1,34 @@
+# PHP/Install
+
+See: [Install.cmake](https://github.com/petk/php-build-system/tree/master/cmake/cmake/modules/PHP/Install.cmake)
+
+Set the `CMAKE_INSTALL_*` variables inside the `install(CODE|SCRIPT)`.
+
+This is built on top of the CMake's `GNUInstallDirs` module. At the time of
+writing, CMake documentation mentions special cases where, for example, the
+`CMAKE_INSTALL_FULL_SYSCONFDIR` variable becomes the `/etc`, when the install
+prefix is `/usr`, and similar.
+
+However, some of these special cases aren't taken into account when using the
+`install()` commands.
+
+This module exposes the following function:
+
+```cmake
+php_install(CODE <code> ...)
+```
+
+It acts the same as `install(CODE <code> ...)`, except that also the
+`CMAKE_INSTALL_*` variables are available inside the <code> argument, like in
+the rest of the CMake code.
+
+```cmake
+php_install(CODE "
+  message(STATUS \"CMAKE_INSTALL_SYSCONFDIR=\${CMAKE_INSTALL_SYSCONFDIR}\")
+")
+```
+
+See:
+
+* https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html
+* https://cmake.org/cmake/help/latest/command/install.html

docs/cmake-modules/PHP/PkgConfigGenerator.md

@@ -48,7 +48,3 @@ template.
   which is replaced with installation prefix either set via the
   `CMAKE_INSTALL_PREFIX` variable at the configuration phase, or the `--prefix`
   option at the `cmake --install` phase.
-
-  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.

docs/cmake-modules/Packages/LibXml2.md

@@ -12,7 +12,7 @@ See: https://cmake.org/cmake/help/latest/module/FindLibXml2.html
 
 The `FetchContent` CMake module does things differently compared to the
 `find_package()` flow:
-* By default it uses `QUIET` in its `find_package()` call when calling the
+* By default, it uses `QUIET` in its `find_package()` call when calling the
   `FetchContent_MakeAvailable()`;
 * When using `FeatureSummary`, dependencies must be moved manually to
   `PACKAGES_FOUND` from the `PACKAGES_NOT_FOUND` global property;

docs/cmake.md

@@ -319,6 +319,7 @@ include(PHP/NewModule)
 
 * [PHP/CheckBuiltin](/docs/cmake-modules/PHP/CheckBuiltin.md)
 * [PHP/CheckCompilerFlag](/docs/cmake-modules/PHP/CheckCompilerFlag.md)
+* [PHP/Install](/docs/cmake-modules/PHP/Install.md)
 * [PHP/SearchLibraries](/docs/cmake-modules/PHP/SearchLibraries.md)
 
 ## 9. Custom CMake properties

docs/dependencies.md

@@ -131,8 +131,8 @@ dependencies.
 Quick usage:
 
 ```sh
-# List of all known package names on the system:
-pkgconf --list-package-names
+# List of all known packages on the system:
+pkgconf --list-all
 
 # Print required linker flags to stdout for given package name:
 pkgconf --libs libcrypt
@@ -150,8 +150,8 @@ pkgconf --help
 PKG_CONFIG_PATH=/path/to/pkgconfig pkgconf --modversion libcrypt
 ```
 
-The `pkgconf` ships with M4 macro file `pkg.m4` for Autotools-based build
-systems and provides several macros, such as `PKG_CHECK_MODULES`.
+The `pkgconf` ships with Autoconf M4 macro file `pkg.m4` for Autotools-based
+build systems and provides several macros, such as `PKG_CHECK_MODULES`.
 
 `PKG_CHECK_MODULES` creates so-called precious variables `*_LIBS` and `*_CFLAGS`
 for using dependency in the build system. See `./configure --help` for all the

docs/php-installation.md

@@ -167,6 +167,7 @@ Common practice is to also add program prefix and suffix (for example, to have
   EXTENSION_DIR=/path/to/php/extensions \
   --with-layout=GNU \
   --localstatedir=/var \
+  --sysconfdir=/etc \
   --program-suffix=84 \
   # ...
 ```
@@ -177,7 +178,7 @@ PHP Autotools directory structure with GNU layout:
 
 ```sh
 📂 <INSTALL_ROOT>                     # 📂
- └─📂 ${prefix}                       # └─📂 /usr/local/include
+ └─📂 ${prefix}                       # └─📂 /usr/local
     ├─📂 ${bindir}                    #    ├─📂 bin
     └─📂 ${sysconfdir}                #    └─📂 etc
        ├─📂 php-fpm.d                 #       ├─📂 php-fpm.d
@@ -201,7 +202,7 @@ PHP Autotools directory structure with GNU layout:
           └─📂 man8                   #          └─📂 man8
        ├─📂 pear                      #       └─📂 pear
        └─📂 php                       #       └─📂 php
-          └─📂 fpm                    #            └─📂 fpm
+          └─📂 fpm                    #          └─📂 fpm
     └─📂 ${localstatedir}             #    └─📂 var
        └─📂 log                       #       └─📂 log
     └─📂 ${runstatedir}               #    └─📂 var/run
@@ -244,7 +245,7 @@ DESTDIR=/stage cmake --install . --prefix /usr
 
 To adjust the installation locations, the
 [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html)
-module is used to set additional `CMAKE_INSTALL_*` variables.
+module is used to set the `CMAKE_INSTALL_*` variables.
 
 * `CMAKE_INSTALL_BINDIR` - name of the bin directory
 * `CMAKE_INSTALL_DATADIR` - name of the etc directory
@@ -310,9 +311,21 @@ PHP installation directory structure when using CMake:
 > [!NOTE]
 > The `DATAROOTDIR` and `DATADIR` are treated separately to be able to adjust
 > only the `DATADIR` with project specific files, while leaving the
-> `DATAROOTDIR` intact for man or other files. See also
+> `DATAROOTDIR` intact for man or other files. See
 > [GNU](https://www.gnu.org/prep/standards/html_node/Directory-Variables.html)
-> explanation for more info.
+> for more info.
+
+> [!NOTE]
+> The CMake `GNUInstallDirs` module also adjusts GNU-related variables according
+> to various standards, so there are some special cases.
+>
+> When the `CMAKE_INSTALL_PREFIX` is set to `/usr`, the `SYSCONFDIR`,
+> `LOCALSTATEDIR`, and `RUNSTATEDIR` become `/etc`, `/var`, and
+> `/var/run` instead of `/usr/etc`, and `/usr/var`, and `/usr/var/run`. Similar
+> adjustments are done when install prefix is `/` or `/opt/...`. See
+> [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html#special-cases)
+> for more info. The [PHP/Install](/docs/cmake-modules/PHP/Install.md) bypasses
+> some of these adjustmens inside the `install()` command for convenience.
 
 Instead of setting the installation prefix at the configuration phase using
 `CMAKE_INSTALL_PREFIX` variable or `--install-prefix` option, there is
@@ -331,13 +344,13 @@ root directory:
       "inherits": "all-enabled",
       "displayName": "Acme PHP configuration",
       "description": "Customized PHP build",
-      "installDir": "/install/prefix",
+      "installDir": "/usr",
       "cacheVariables": {
         "CMAKE_INSTALL_BINDIR": "home/user/.local/bin",
         "PHP_BUILD_SYSTEM": "Acme Linux",
         "PHP_BUILD_PROVIDER": "Acme",
         "PHP_BUILD_COMPILER": "GCC",
-        "PHP_BUILD_ARCH": "x86",
+        "PHP_BUILD_ARCH": "x86_64",
         "PHP_VERSION_LABEL": "-acme",
         "PHP_EXTENSION_DIR": "lib/php83/extensions"
       }