Skip to content

Commit 6130605

Browse files
petkpetk
committed
Update docs
- bin/make-docs.php script updated for the new CMake modules locations - CMake-based build system docs updated according to current changes - docs/cmake/modules regenerated
1 parent c041150 commit 6130605

File tree

105 files changed

+1166
-145
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

105 files changed

+1166
-145
lines changed

‎bin/make-docs.php‎

Lines changed: 116 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -11,70 +11,143 @@
1111
*/
1212

1313
/**
14-
* Get CMake module header content.
14+
* Generate CMake module Markdown docs file from the file's header comment.
1515
*/
1616
function generateModuleDocs(
1717
string $file,
1818
string $namespace,
1919
string $destination,
20-
string $url = '',
20+
string $url,
2121
): void {
2222
$content = file_get_contents($file);
2323
preg_match('/^#\[===+\[\s*(.*?)\s*#\]===+\]/s', $content, $matches);
2424

25-
if (isset($matches[1])) {
26-
$moduleName = basename($file, '.cmake');
25+
if (!isset($matches[1])) {
26+
return;
27+
}
2728

28-
$content = '';
29-
$content .= "# $namespace" . "$moduleName\n\n";
30-
if ('' === $url) {
31-
$url = 'https://github.com/petk/php-build-system/tree/master/cmake/cmake/modules/' . $namespace . $moduleName . '.cmake';
32-
}
33-
$content .= "See: [$moduleName.cmake]($url)\n\n";
34-
$content .= $matches[1];
35-
$content .= "\n";
29+
$moduleName = basename($file, '.cmake');
3630

37-
if (!file_exists($destination . '/' . $namespace)) {
38-
mkdir($destination . '/' . $namespace, 0777, true);
39-
}
31+
$content = '';
32+
$content .= "# $namespace" . "$moduleName\n\n";
33+
$content .= "See: [$moduleName.cmake]($url)\n\n";
34+
if ($namespace) {
35+
$content .= <<<EOT
36+
## Basic usage
4037
41-
file_put_contents(
42-
$destination . '/' . $namespace . $moduleName . '.md',
43-
$content,
44-
);
38+
```cmake
39+
include({$namespace}{$moduleName})
40+
```
41+
EOT;
42+
} elseif (1 === preg_match('/^Find.+.cmake$/', $moduleName)) {
43+
$content .= <<<EOT
44+
## Basic usage
45+
46+
```cmake
47+
find_package($moduleName)
48+
```
49+
EOT;
50+
} else {
51+
$content .= <<<EOT
52+
## Basic usage
53+
54+
```cmake
55+
include(cmake/$moduleName.cmake)
56+
```
57+
EOT;
4558
}
46-
}
59+
$content .= "\n\n";
60+
$content .= $matches[1];
61+
$content .= "\n";
4762

48-
$docs = __DIR__ . '/../docs/cmake/modules';
49-
if (!file_exists($docs)) {
50-
mkdir($docs, 0777, true);
63+
if (!file_exists($destination)) {
64+
mkdir($destination, 0777, true);
65+
}
66+
67+
$markdownFile = $destination . '/' . $moduleName . '.md';
68+
if (file_exists($markdownFile)) {
69+
echo "\nWarning: $markdownFile already exists.\n";
70+
$markdownFile = $destination . '/' . $moduleName . '_2.md';
71+
echo "Module has been renamed to $markdownFile\n\n";
72+
}
73+
74+
file_put_contents($markdownFile, $content);
5175
}
5276

53-
$docFiles = glob($docs . '/*{/*,*}', GLOB_BRACE);
54-
foreach ($docFiles as $file) {
55-
if (is_file($file)) {
56-
unlink($file);
77+
/**
78+
* Remove directory contents recursively.
79+
*/
80+
function emptyDirectory(string $path): void
81+
{
82+
$iterator = new RecursiveIteratorIterator(
83+
new RecursiveDirectoryIterator($path, RecursiveDirectoryIterator::SKIP_DOTS),
84+
RecursiveIteratorIterator::CHILD_FIRST,
85+
);
86+
87+
foreach ($iterator as $file) {
88+
if ($file->isDir()) {
89+
rmdir($file->getPathname());
90+
} else {
91+
unlink($file->getPathname());
92+
}
5793
}
5894
}
5995

60-
$modulesDirectory = realpath(__DIR__ . '/../cmake/cmake/modules');
61-
$files = glob($modulesDirectory . '/*{/*,*}.cmake', GLOB_BRACE);
96+
$modulesDocsDir = __DIR__ . '/../docs/cmake/modules';
6297

63-
foreach ($files as $file) {
64-
$relativeFilename = trim(str_replace($modulesDirectory, '', $file), '/');
65-
echo 'Processing ' . $relativeFilename . "\n";
98+
if (!file_exists($modulesDocsDir)) {
99+
mkdir($modulesDocsDir, 0777, true);
100+
} else {
101+
emptyDirectory($modulesDocsDir);
102+
}
103+
104+
$modules = [
105+
'cmake/modules',
106+
'cmake/modules/Packages',
107+
'cmake/modules/PHP',
108+
'ext/opcache/cmake',
109+
'ext/posix/cmake',
110+
'ext/session/cmake',
111+
'ext/skeleton/cmake/modules/FindPHP.cmake',
112+
'ext/standard/cmake',
113+
'sapi/fpm/cmake',
114+
'sapi/phpdbg/cmake',
115+
'Zend/cmake',
116+
];
66117

67-
$namespace = trim(str_replace($modulesDirectory, '', dirname($file)), '/');
68-
$namespace = ('' == $namespace) ? '' : $namespace . '/';
118+
$baseDir = __DIR__ . '/../cmake';
69119

70-
generateModuleDocs($file, $namespace, $docs);
120+
$files = [];
121+
foreach ($modules as $module) {
122+
if (is_dir($baseDir . '/' . $module)) {
123+
$foundFiles = glob($baseDir . '/' . $module . '/*.cmake', GLOB_BRACE);
124+
$files = array_merge($files, $foundFiles);
125+
} else {
126+
$files[] = $baseDir . '/' . $module;
127+
}
71128
}
72129

73-
// Add ext/skeleton/cmake/modules/FindPHP.cmake.
74-
echo "Processing ext/skeleton/cmake/modules/FindPHP.cmake\n";
75-
generateModuleDocs(
76-
__DIR__ . '/../cmake/ext/skeleton/cmake/modules/FindPHP.cmake',
77-
'',
78-
$docs,
79-
'https://github.com/petk/php-build-system/blob/master/cmake/ext/skeleton/cmake/modules/FindPHP.cmake',
80-
);
130+
foreach ($files as $module) {
131+
$relativeFilename = trim(str_replace($baseDir, '', $module), '/');
132+
133+
if (str_starts_with($module, $baseDir . '/cmake/modules/')) {
134+
$namespace = trim(str_replace($baseDir . '/cmake/modules', '', dirname($module)), '/');
135+
$namespace = ('' == $namespace) ? '' : $namespace . '/';
136+
$subdir = $namespace;
137+
} else {
138+
$namespace = '';
139+
if ('FindPHP.cmake' === basename($module)) {
140+
$subdir = '';
141+
} else {
142+
$subdir = basename(dirname($module, 2));
143+
}
144+
}
145+
146+
echo "Processing cmake/$relativeFilename\n";
147+
generateModuleDocs(
148+
$module,
149+
$namespace,
150+
$modulesDocsDir . '/' . $subdir,
151+
'https://github.com/petk/php-build-system/blob/master/cmake/' . $relativeFilename,
152+
);
153+
}

‎docs/cmake/cmake-code-style.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -379,6 +379,11 @@ include(PHP/PascalCase)
379379
This approach is adopted for convenience to prevent any potential conflicts with
380380
upstream CMake modules.
381381

382+
> [!TIP]
383+
> When `CMakeLists.txt` becomes too complex for all-in-one configuration file,
384+
> some PHP extensions, SAPIs and Zend Engine include configure checks from local
385+
> modules located in their `cmake` subdirectories for simplicity.
386+
382387
## 5. Booleans
383388

384389
CMake interprets `1`, `ON`, `YES`, `TRUE`, and `Y` as representing boolean true

‎docs/cmake/cmake.md‎

Lines changed: 47 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -34,34 +34,38 @@ repository:
3434
📂 <php-src>
3535
└─📂 cmake # CMake-based PHP build system files
3636
└─📂 modules # Project-specific CMake modules
37-
├─📂 PHP # PHP utility modules
38-
├─📂 Zend # Zend utility modules
39-
├─📄 Find*.cmake # Find modules that support the find_package()
40-
└─📄 *.cmake # Any possible additional utility modules
37+
├─📂 PHP # PHP utility CMake modules
38+
└─📄 Find*.cmake # Find modules that support the find_package()
4139
├─📂 platforms # Platform-specific configuration
4240
├─📂 presets # Presets included in CMakePresets.json
4341
├─📂 scripts # Various CMake command-line scripts
4442
├─📂 toolchains # CMake toolchain files
45-
└─📄 *.cmake # Various CMake configurations and tools
43+
└─📄 *.cmake # Various CMake configurations and files
4644
└─📂 ext
4745
└─📂 date
48-
└─📄 CMakeLists.txt # Extension's CMake file
46+
├─📄 CMakeLists.txt # Extension's CMake file
47+
└─📄 config.cmake.h.in # Extension's configuration header template
4948
└─📂 iconv
5049
├─📄 CMakeLists.txt
50+
├─📄 config.cmake.h.in
5151
└─📄 php_iconv.def # Module-definition for building DLL on Windows
5252
└─📂 mbstring
5353
└─📂 libmbfl
5454
└─📄 config.h.in # Configuration header template for libmbfl
55+
└─📂 standard
56+
├─📂 cmake # Extension's local utility CMake modules
57+
└─📄 CMakeLists.txt
5558
└─📂 main
56-
├─📄 internal_functions.c.in # Template for internal functions files
5759
├─📄 CMakeLists.txt # CMake file for main binding
58-
├─📄 config.w32.cmake.h.in # Windows configuration header template
60+
├─📄 internal_functions.c.in # Template for internal functions files
5961
└─📄 php_config.cmake.h.in # Configuration header template
6062
└─📂 pear
6163
└─📄 CMakeLists.txt # CMake file for PEAR
6264
└─📂 sapi
63-
└─📂 cli
64-
└─📄 CMakeLists.txt # CMake file for PHP SAPI module
65+
└─📂 fpm
66+
├─📂 cmake # SAPI's CMake modules and files
67+
├─📄 CMakeLists.txt # CMake file for PHP SAPI module
68+
└─📄 config.cmake.h.in # SAPI's configuration header template
6569
└─📂 scripts
6670
└─📄 CMakeLists.txt # CMake file for creating scripts files
6771
└─📂 TSRM
@@ -71,7 +75,9 @@ repository:
7175
└─📄 wsyslog.mc # Message template file for win32/wsyslog.h
7276
└─📄 CMakeLists.txt # CMake file for Windows build
7377
└─📂 Zend
74-
└─📄 CMakeLists.txt # CMake file for Zend Engine
78+
├─📂 cmake # Zend Engine related CMake modules and files
79+
├─📄 CMakeLists.txt # CMake file for Zend Engine
80+
└─📄 zend_config.cmake.h.in # Zend Engine configuration header template
7581
├─📄 CMakeLists.txt # Root CMake file
7682
├─📄 CMakePresets.json # Main CMake presets file
7783
└─📄 CMakeUserPresets.json # Git ignored local CMake presets overrides
@@ -102,9 +108,12 @@ Required:
102108
* cmake
103109
* gcc
104110
* g++
105-
* libxml2
106111
* libsqlite3
107112

113+
Optional (if not found on the system, build system tries to download it):
114+
115+
* libxml2
116+
108117
Additionally required when building from Git repository source code:
109118

110119
* bison
@@ -313,20 +322,36 @@ target_link_libraries(target_name PRIVATE PHP::configuration)
313322

314323
## 8. PHP CMake modules
315324

316-
All PHP CMake utility modules are located in the `cmake/modules/PHP` directory.
325+
All PHP global CMake utility modules are located in the `cmake/modules/PHP`
326+
directory.
317327

318-
Here are listed only those that are important when adapting PHP build system.
319-
Otherwise, a new module can be added by creating a new CMake file
320-
`cmake/modules/PHP/NewModule.cmake` and then include it in the CMake code:
328+
A new module can be added by creating a new CMake file
329+
`cmake/modules/PHP/NewModule.cmake` which can be then included in the CMake
330+
files:
321331

322332
```cmake
323333
include(PHP/NewModule)
324334
```
325335

336+
Additional CMake modules or other files that are used only inside a certain
337+
subdirectory (extension, SAPI, Zend Engine...) are located in the `cmake`
338+
directories where needed:
339+
340+
* `ext/<extension>/cmake/*.cmake` - CMake modules related to extension
341+
* `sapi/<sapi>/cmake/*.cmake` - CMake modules related to SAPI
342+
* `Zend/cmake/*.cmake` - CMake modules related to Zend Engine
343+
344+
A list of PHP CMake modules:
345+
346+
* [PHP/AddCustomCommand](/docs/cmake/modules/PHP/AddCustomCommand.md)
347+
* [PHP/CheckAttribute](/docs/cmake/modules/PHP/CheckAttribute.md)
326348
* [PHP/CheckBuiltin](/docs/cmake/modules/PHP/CheckBuiltin.md)
327349
* [PHP/CheckCompilerFlag](/docs/cmake/modules/PHP/CheckCompilerFlag.md)
350+
* [PHP/ConfigureFile](/docs/cmake/modules/PHP/ConfigureFile.md)
328351
* [PHP/Install](/docs/cmake/modules/PHP/Install.md)
329352
* [PHP/SearchLibraries](/docs/cmake/modules/PHP/SearchLibraries.md)
353+
* [PHP/Set](/docs/cmake/modules/PHP/Set.md)
354+
* [PHP/SystemExtensions](/docs/cmake/modules/PHP/SystemExtensions.md)
330355

331356
## 9. Custom CMake properties
332357

@@ -414,6 +439,10 @@ PECL tool is a simple shell script wrapper around the PHP code as part of the
414439
[pear-core](https://github.com/pear/pear-core/blob/master/scripts/pecl.sh)
415440
repository.
416441

442+
> [!NOTE]
443+
> `pecl` command-line script is also being replaced with a new tool
444+
> [PIE](https://github.com/php/pie).
445+
417446
To build PHP extensions with CMake, a `CMakeLists.txt` file needs to be added to
418447
the extension's source directory.
419448

@@ -466,7 +495,8 @@ also tracked in the Git repository for a smoother workflow:
466495
├─📄 cp_enc_map.c # Generated from win32/cp_enc_map_gen.c
467496
└─📄 wsyslog.h # Generated by message compiler (mc.exe or windmc)
468497
└─📂 Zend
469-
├─📄 zend_config.w32.h # Zend Engine configuration header for Windows
498+
├─📄 zend_config.h # Zend Engine configuration header on *nix systems
499+
├─📄 zend_config.w32.h # Zend Engine configuration header on Windows
470500
├─📄 zend_vm_execute.h # Generated by `Zend/zend_vm_gen.php`
471501
├─📄 zend_vm_opcodes.c # Generated by `Zend/zend_vm_gen.php`
472502
└─📄 zend_vm_opcodes.h # Generated by `Zend/zend_vm_gen.php`

‎docs/cmake/modules/FindACL.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# FindACL
22

3-
See: [FindACL.cmake](https://github.com/petk/php-build-system/tree/master/cmake/cmake/modules/FindACL.cmake)
3+
See: [FindACL.cmake](https://github.com/petk/php-build-system/blob/master/cmake/cmake/modules/FindACL.cmake)
4+
5+
## Basic usage
6+
7+
```cmake
8+
include(cmake/FindACL.cmake)
9+
```
410

511
Find the ACL library.
612

‎docs/cmake/modules/FindApache.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# FindApache
22

3-
See: [FindApache.cmake](https://github.com/petk/php-build-system/tree/master/cmake/cmake/modules/FindApache.cmake)
3+
See: [FindApache.cmake](https://github.com/petk/php-build-system/blob/master/cmake/cmake/modules/FindApache.cmake)
4+
5+
## Basic usage
6+
7+
```cmake
8+
include(cmake/FindApache.cmake)
9+
```
410

511
Find the Apache packages and tools.
612

‎docs/cmake/modules/FindAppArmor.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# FindAppArmor
22

3-
See: [FindAppArmor.cmake](https://github.com/petk/php-build-system/tree/master/cmake/cmake/modules/FindAppArmor.cmake)
3+
See: [FindAppArmor.cmake](https://github.com/petk/php-build-system/blob/master/cmake/cmake/modules/FindAppArmor.cmake)
4+
5+
## Basic usage
6+
7+
```cmake
8+
include(cmake/FindAppArmor.cmake)
9+
```
410

511
Find the AppArmor library.
612

‎docs/cmake/modules/FindArgon2.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
# FindArgon2
22

3-
See: [FindArgon2.cmake](https://github.com/petk/php-build-system/tree/master/cmake/cmake/modules/FindArgon2.cmake)
3+
See: [FindArgon2.cmake](https://github.com/petk/php-build-system/blob/master/cmake/cmake/modules/FindArgon2.cmake)
4+
5+
## Basic usage
6+
7+
```cmake
8+
include(cmake/FindArgon2.cmake)
9+
```
410

511
Find the Argon2 library.
612

0 commit comments

Comments
 (0)