Add docs for gnu static build

docs/.vitepress/sidebar.en.ts

@@ -1,22 +1,24 @@
 export default {
   '/en/guide/': [
     {
-      text: 'Guide',
+      text: 'Basic Build Guides',
       items: [
         {text: 'Guide', link: '/en/guide/'},
-        {text: 'Actions Build', link: '/en/guide/action-build'},
-        {text: 'Manual Build', link: '/en/guide/manual-build'},
-        {text: 'Extension List', link: '/en/guide/extensions'},
+        {text: 'Build (Local)', link: '/en/guide/manual-build'},
+        {text: 'Build (CI)', link: '/en/guide/action-build'},
+        {text: 'Supported Extensions', link: '/en/guide/extensions'},
         {text: 'Extension Notes', link: '/en/guide/extension-notes'},
-        {text: 'Command Generator', link: '/en/guide/cli-generator'},
+        {text: 'Build Command Generator', link: '/en/guide/cli-generator'},
         {text: 'Environment Variables', link: '/en/guide/env-vars', collapsed: true,},
         {text: 'Dependency Table', link: '/en/guide/deps-map'},
       ]
     },
     {
+      text: 'Extended Build Guides',
       items: [
         {text: 'Troubleshooting', link: '/en/guide/troubleshooting'},
         {text: 'Build on Windows', link: '/en/guide/build-on-windows'},
+        {text: 'Build with glibc (experimental)', link: '/en/guide/build-with-glibc'},
       ],
     }
   ],

docs/.vitepress/sidebar.zh.ts

@@ -4,8 +4,8 @@ export default {
       text: '构建指南',
       items: [
         {text: '指南', link: '/zh/guide/'},
-        {text: 'Actions 构建', link: '/zh/guide/action-build'},
         {text: '本地构建', link: '/zh/guide/manual-build'},
+        {text: 'Actions 构建', link: '/zh/guide/action-build'},
         {text: '扩展列表', link: '/zh/guide/extensions'},
         {text: '扩展注意事项', link: '/zh/guide/extension-notes'},
         {text: '编译命令生成器', link: '/zh/guide/cli-generator'},
@@ -14,9 +14,11 @@ export default {
       ]
     },
     {
+      text: '扩展构建指南',
       items: [
         {text: '故障排除', link: '/zh/guide/troubleshooting'},
         {text: '在 Windows 上构建', link: '/zh/guide/build-on-windows'},
+        {text: '构建 glibc 兼容的二进制', link: '/zh/guide/build-with-glibc'},
       ],
     }
   ],

docs/en/guide/build-with-glibc.md

@@ -0,0 +1,83 @@
+# Build glibc Compatible Linux Binary
+
+## Why Build glibc Compatible Binary
+
+Currently, the binaries built by static-php-cli on Linux by default are based on musl-libc (statically linked). 
+musl-libc is a lightweight libc implementation 
+that aims to be compatible with glibc and provides good support for pure static linking. 
+This means that the compiled static PHP executable can be used on almost any Linux distribution without worrying about the versions of libc, libstdc++, etc.
+
+However, there are some issues with pure static linking of musl-libc binaries on Linux:
+
+- The `dl()` function in PHP cannot be used to load dynamic libraries and external PHP extensions.
+- The FFI extension in PHP cannot be used.
+- In some extreme cases, performance issues may occur. See [musl-libc performance issues](https://github.com/php/php-src/issues/13648).
+
+Different Linux distributions use different default libc. F
+or example, Alpine Linux uses musl libc, while most Linux distributions use glibc. 
+However, even so, we cannot directly use any distribution using glibc to build portable static binaries because glibc has some issues:
+
+- Binaries built with gcc and other tools on newer versions of distributions cannot run on older versions of distributions.
+- glibc is not recommended to be statically linked because some of its features require the support of dynamic libraries.
+
+However, we can use Docker to solve this problem. 
+The final output is a binary **dynamically linked with glibc** and some necessary libraries, 
+but **statically linked with all other dependencies**.
+
+1. Use an older version of a Linux distribution (such as CentOS 7.x), which has an older version of glibc but can run on most modern Linux distributions.
+2. Build the static binary of PHP in this container so that it can run on most modern Linux distributions.
+
+> Using glibc static binaries can run on most modern Linux distributions but cannot run on musl libc distributions, such as CentOS 6, Alpine Linux, etc.
+
+## Build glibc Compatible Linux Binary
+
+The latest version of static-php-cli includes the `bin/spc-gnu-docker` script, 
+which can create a CentOS 7.x (glibc-2.17) Docker container with one click and build a glibc compatible PHP static binary in the container.
+
+First, clone the repository of this project and add the following content to the `config/env.custom.ini` file:
+
+```ini
+; Modify this file name to `env.custom.ini`, and run `bin/spc-gnu-docker`,
+; you can compile a GNU libc based static binary !
+[global]
+SPC_SKIP_DOCTOR_CHECK_ITEMS="if musl-wrapper is installed,if musl-cross-make is installed"
+
+[linux]
+CC=gcc
+CXX=g++
+AR=ar
+LD=ld
+SPC_DEFAULT_C_FLAGS=-fPIC
+SPC_NO_MUSL_PATH=yes
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM="-Wl,-O1 -pie"
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS="-ldl -lpthread -lm -lresolv -lutil"
+```
+
+Then, run the following command once. 
+The first run will take a long time because it needs to download the CentOS 7.x image and some build tools.
+
+```bash
+bin/spc-gnu-docker
+```
+
+After the image is built, you will see the same command help menu as `bin/spc`, which means the container is ready.
+
+After the container is ready, you can refer to the [local build](./manual-build) section to build your PHP static binary. 
+Just replace `bin/spc` or `./spc` with `bin/spc-gnu-docker`.
+
+Unlike the default build, when building in the glibc environment, you **must** add the parameter `--libc=glibc`, such as:
+
+```bash
+bin/spc-gnu-docker --libc=glibc build bcmath,ctype,openssl,pdo,phar,posix,session,tokenizer,xml,zip --build-cli --debug
+```
+
+## Notes
+
+In rare cases, glibc-based static PHP may encounter segment faults and other errors, but there are currently few examples. 
+If you encounter any issues, please submit an issue.
+
+glibc build is an extended feature and is not part of the default static-php support. 
+If you have related issues or requirements, please indicate that you are building based on glibc when submitting an issue.
+
+If you need to build glibc-based binaries without using Docker, 
+please refer to the `bin/spc-gnu-docker` script to manually create a similar environment.

docs/zh/guide/build-with-glibc.md

@@ -0,0 +1,71 @@
+# 构建 glibc 兼容的 Linux 二进制
+
+## 为什么要构建 glibc 兼容的二进制
+
+目前，static-php-cli 在默认条件下在 Linux 系统构建的二进制都是基于 musl-libc（静态链接）的。
+musl-libc 是一个轻量级的 libc 实现，它的目标是与 glibc 兼容，并且提供良好的纯静态链接支持。
+这意味着，编译出来的静态 PHP 可执行文件在几乎任何 Linux 发行版都可以使用，而不需要考虑 libc、libstdc++ 等库的版本问题。
+
+但是，Linux 系统的纯静态链接 musl-libc 二进制文件存在以下问题：
+
+- 无法使用 PHP 的 `dl()` 函数加载动态链接库和外部 PHP 扩展。
+- 无法使用 PHP 的 FFI 扩展。
+- 部分极端情况下，可能会出现性能问题，参见 [musl-libc 的性能问题](https://github.com/php/php-src/issues/13648)。
+
+对于不同的 Linux 发行版，它们使用的默认 libc 可能不同，比如 Alpine Linux 使用 musl libc，而大多数 Linux 发行版使用 glibc。
+但即便如此，我们也不能直接使用任意的发行版和 glibc 构建便携的静态二进制文件，因为 glibc 有一些问题：
+
+- 基于新版本的发行版在使用 gcc 等工具构建的二进制，无法在旧版本的发行版上运行。
+- glibc 不推荐被静态链接，因为它的一些特性需要动态链接库的支持。
+
+但是，我们可以使用 Docker 容器来解决这个问题，最终输出的结果是一个动态链接 glibc 和一些必要库的二进制，但它静态链接所有其他依赖。
+
+1. 使用一个旧版本的 Linux 发行版（如 CentOS 7.x），它的 glibc 版本比较旧，但是可以在大多数现代 Linux 发行版上运行。
+2. 在这个容器中构建 PHP 的静态二进制文件，这样就可以在大多数现代 Linux 发行版上运行了。
+
+> 使用 glibc 的静态二进制文件，可以在大多数现代 Linux 发行版上运行，但是不能在 musl libc 的发行版上运行，如 CentOS 6、Alpine Linux 等。
+
+## 构建 glibc 兼容的 Linux 二进制
+
+最新版的 static-php-cli 内置了 `bin/spc-gnu-docker` 脚本，可以一键创建一个 CentOS 7.x (glibc-2.17) 的 Docker 容器，并在容器中构建 glibc 兼容的 PHP 静态二进制文件。
+
+请先克隆本项目的仓库，并将下面的内容添加到 `config/env.custom.ini` 文件中：
+
+```ini
+; Modify this file name to `env.custom.ini`, and run `bin/spc-gnu-docker`,
+; you can compile a GNU libc based static binary !
+[global]
+SPC_SKIP_DOCTOR_CHECK_ITEMS="if musl-wrapper is installed,if musl-cross-make is installed"
+
+[linux]
+CC=gcc
+CXX=g++
+AR=ar
+LD=ld
+SPC_DEFAULT_C_FLAGS=-fPIC
+SPC_NO_MUSL_PATH=yes
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM="-Wl,-O1 -pie"
+SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS="-ldl -lpthread -lm -lresolv -lutil"
+```
+
+然后，先运行一次以下命令。首次运行时时间较长，因为需要下载 CentOS 7.x 的镜像和一些编译工具。
+
+```bash
+bin/spc-gnu-docker
+```
+
+构建镜像完成后，你将看到和 `bin/spc` 一样的命令帮助菜单，这时说明容器已经准备好了。
+
+在容器准备好后，你可以参考 [本地构建](./manual-build) 章节的内容，构建你的 PHP 静态二进制文件。仅需要把 `bin/spc` 或 `./spc` 替换为 `bin/spc-gnu-docker` 即可。
+
+与默认构建不同的是，在 glibc 环境构建时**必须添加**参数 `--libc=glibc`，如：
+
+```bash
+bin/spc-gnu-docker --libc=glibc build bcmath,ctype,openssl,pdo,phar,posix,session,tokenizer,xml,zip --build-cli --debug
+```
+
+## 注意事项
+
+- 极少数情况下，基于 glibc 的静态 PHP 可能会出现 segment fault 等错误，但目前例子较少，如果遇到问题请提交 issue。
+- glibc 构建为扩展的特性，不属于默认 static-php 的支持范围。如果有相关问题或需求，请在提交 Issue 时注明你是基于 glibc 构建的。
+- 如果你需要不使用 Docker 构建基于 glibc 的二进制，请参考 `bin/spc-gnu-docker` 脚本，手动构建一个类似的环境。