From 0aab10ba31611a6aa1aff220b76ee6aac94b8703 Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Tue, 4 Feb 2025 17:20:27 +0800 Subject: [PATCH] Add docs for gnu static build --- docs/.vitepress/sidebar.en.ts | 12 +++-- docs/.vitepress/sidebar.zh.ts | 4 +- docs/en/guide/build-with-glibc.md | 83 +++++++++++++++++++++++++++++++ docs/zh/guide/build-with-glibc.md | 71 ++++++++++++++++++++++++++ 4 files changed, 164 insertions(+), 6 deletions(-) create mode 100644 docs/en/guide/build-with-glibc.md create mode 100644 docs/zh/guide/build-with-glibc.md diff --git a/docs/.vitepress/sidebar.en.ts b/docs/.vitepress/sidebar.en.ts index b9c80aae..8efcc265 100644 --- a/docs/.vitepress/sidebar.en.ts +++ b/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'}, ], } ], diff --git a/docs/.vitepress/sidebar.zh.ts b/docs/.vitepress/sidebar.zh.ts index a17ac0f0..36910c60 100644 --- a/docs/.vitepress/sidebar.zh.ts +++ b/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'}, ], } ], diff --git a/docs/en/guide/build-with-glibc.md b/docs/en/guide/build-with-glibc.md new file mode 100644 index 00000000..f8c307b1 --- /dev/null +++ b/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. diff --git a/docs/zh/guide/build-with-glibc.md b/docs/zh/guide/build-with-glibc.md new file mode 100644 index 00000000..75e25d66 --- /dev/null +++ b/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` 脚本，手动构建一个类似的环境。