From ee8d9eeee9ca2f14e670f4e396c11fe5f98491ad Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Thu, 3 Oct 2024 14:53:25 +0800 Subject: [PATCH] Update env-vars docs --- config/env.ini | 6 +- docs/en/guide/env-vars.md | 108 +++++++----------------------------- docs/zh/guide/env-vars.md | 112 +++++++------------------------------- 3 files changed, 43 insertions(+), 183 deletions(-) diff --git a/config/env.ini b/config/env.ini index d84d0acb..e6ee7180 100644 --- a/config/env.ini +++ b/config/env.ini @@ -39,12 +39,12 @@ [global] -; Build concurrency for make -jN +; Build concurrency for make -jN, default is CPU_COUNT, this value are used in every lib and php builds. SPC_CONCURRENCY=${CPU_COUNT} ; Ignore PHP version check before building some extensions SPC_SKIP_PHP_VERSION_CHECK="no" -; Ignore some check item for bin/spc doctor command, comma separated -SPC_SKIP_DOCTOR_CHECK_ITEMS="if homebrew has installed" +; Ignore some check item for bin/spc doctor command, comma separated (e.g. SPC_SKIP_DOCTOR_CHECK_ITEMS="if homebrew has installed") +SPC_SKIP_DOCTOR_CHECK_ITEMS="" [windows] ; php-sdk-binary-tools path diff --git a/docs/en/guide/env-vars.md b/docs/en/guide/env-vars.md index f60b1d2d..10581733 100644 --- a/docs/en/guide/env-vars.md +++ b/docs/en/guide/env-vars.md @@ -1,12 +1,23 @@ ---- -aside: false ---- - # Environment variables All environment variables mentioned in the list on this page have default values unless otherwise noted. You can override the default values by setting these environment variables. +## Environment variables list + +Starting from version 2.3.5, we have centralized the environment variables in the `config/env.ini` file. +You can set environment variables by modifying this file. + +We divide the environment variables supported by static-php-cli into three types: + +- Global internal environment variables: declared after static-php-cli starts, you can use `getenv()` to get them internally in static-php-cli, and you can override them before starting static-php-cli. +- Fixed environment variables: declared after static-php-cli starts, you can only use `getenv()` to get them, but you cannot override them through shell scripts. +- Config file environment variables: declared before static-php-cli build, you can set these environment variables by modifying the `config/env.ini` file or through shell scripts. + +You can read the comments for each parameter in [config/env.ini](https://github.com/crazywhalecc/static-php-cli/blob/main/config/env.ini) to understand its purpose. + +## Custom environment variables + Generally, you don't need to modify any of the following environment variables as they are already set to optimal values. However, if you have special needs, you can set these environment variables to meet your needs (for example, you need to debug PHP performance under different compilation parameters). @@ -22,94 +33,13 @@ bin/spc build mbstring,pcntl --build-cli SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli ``` -## General environment variables +Or, if you need to modify an environment variable for a long time, you can modify the `config/env.ini` file. -General environment variables can be used by all build targets. +`config/env.ini` is divided into three sections, `[global]` is globally effective, `[windows]`, `[macos]`, `[linux]` are only effective for the corresponding operating system. -| var name | default value | comment | -|------------------------------|---------------------------|-------------------------------------------------| -| `BUILD_ROOT_PATH` | `{pwd}/buildroot` | The root directory of the build target | -| `BUILD_LIB_PATH` | `{pwd}/buildroot/lib` | The root directory of compilation libraries | -| `BUILD_INCLUDE_PATH` | `{pwd}/buildroot/include` | Header file directory for compiling libraries | -| `BUILD_BIN_PATH` | `{pwd}/buildroot/bin` | Compiled binary file directory | -| `PKG_ROOT_PATH` | `{pwd}/pkgroot` | Directory where precompiled tools are installed | -| `SOURCE_PATH` | `{pwd}/source` | The source code extract directory | -| `DOWNLOAD_PATH` | `{pwd}/downloads` | Downloaded file directory | -| `SPC_CONCURRENCY` | Depends on CPU cores | Number of parallel compilations | -| `SPC_SKIP_PHP_VERSION_CHECK` | empty | Skip PHP version check when set to `yes` | +For example, if you need to modify the `./configure` command for compiling PHP, you can find the `SPC_CMD_PREFIX_PHP_CONFIGURE` environment variable in the `config/env.ini` file, and then modify its value. -## OS specific variables - -These environment variables are system-specific and will only take effect on a specific OS. - -### Windows - -| var name | default value | comment | -|---------------------|-----------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| -| `PHP_SDK_PATH` | `{pwd}\php-sdk-binary-tools` | PHP SDK tools path | -| `UPX_EXEC` | `$PKG_ROOT_PATH\bin\upx.exe` | UPX compression tool path | -| `SPC_MICRO_PATCHES` | `static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream,cli_static` | Used phpmicro [patches](https://github.com/easysoft/phpmicro/blob/master/patches/Readme.md) | - -### macOS - -| var name | default value | comment | -|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| -| `CC` | `clang` | C Compiler | -| `CXX` | `clang++` | C++ Compiler | -| `SPC_DEFAULT_C_FLAGS` | `--target=arm64-apple-darwin` or `--target=x86_64-apple-darwin` | Default C flags (not the same as `CFLAGS`) | -| `SPC_DEFAULT_CXX_FLAGS` | `--target=arm64-apple-darwin` or `--target=x86_64-apple-darwin` | Default C flags (not the same as `CPPFLAGS`) | -| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | PHP `buildconf` command prefix | -| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | PHP `configure` command prefix | -| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | PHP `make` command prefix | -| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS -Werror=unknown-warning-option` | `CFLAGS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | `CPPFLAGS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | `LDFLAGS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os` or `-g -O0` (the latter when using `--no-strip`) | `EXTRA_CFLAGS` variable of PHP `make` command | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | `-lresolv` | Extra `EXTRA_LIBS` variables for PHP `make` command | -| `SPC_MICRO_PATCHES` | `static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream,macos_iconv` | Used phpmicro [patches](https://github.com/easysoft/phpmicro/blob/master/patches/Readme.md) | - -### Linux - -| var name | default value | comment | -|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------| -| `UPX_EXEC` | `$PKG_ROOT_PATH/bin/upx` | UPX compression tool path | -| `GNU_ARCH` | `x86_64` or `aarch64` | CPU architecture | -| `CC` | Alpine: `gcc`, Other: `$GNU_ARCH-linux-musl-gcc` | C Compiler | -| `CXX` | Alpine: `g++`, Other: `$GNU_ARCH-linux-musl-g++` | C++ Compiler | -| `AR` | Alpine: `ar`, Other: `$GNU_ARCH-linux-musl-ar` | Static library tools | -| `LD` | `ld.gold` | Linker | -| `PATH` | `/usr/local/musl/bin:/usr/local/musl/$GNU_ARCH-linux-musl/bin:$PATH` | System PATH | -| `SPC_DEFAULT_C_FLAGS` | empty | Default C flags | -| `SPC_DEFAULT_CXX_FLAGS` | empty | Default C++ flags | -| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | PHP `buildconf` command prefix | -| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `LD_LIBRARY_PATH={ld_lib_path} ./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | PHP `configure` command prefix | -| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | PHP `make` command prefix | -| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS` | `CFLAGS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | `CPPFLAGS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | `LDFLAGS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_CONFIGURE_LIBS` | `-ldl -lpthread` | `LIBS` variable of PHP `configure` command | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os -fno-ident -fPIE` or `-g -O0 -fno-ident -fPIE` (the latter when using `--no-strip`) | `EXTRA_CFLAGS` variable of PHP `make` command | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | empty | Extra `EXTRA_LIBS` variables for PHP `make` command | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM` | `-all-static` (when using `clang`: `-Xcompiler -fuse-ld=lld -all-static`) | Additional `LDFLAGS` variable for `make` command | -| `SPC_NO_MUSL_PATH` | empty | Whether to not insert the PATH of the musl toolchain (not inserted when the value is `yes`) | -| `SPC_MICRO_PATCHES` | `static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream` | Used phpmicro [patches](https://github.com/easysoft/phpmicro/blob/master/patches/Readme.md) | -> `{ld_lib_path}` value is `/usr/local/musl/$GNU_ARCH-linux-musl/lib`。 - -### FreeBSD - -Due to the small number of users of the FreeBSD system, we do not provide environment variables for the FreeBSD system for the time being. - -### Unix - -For Unix systems such as macOS, Linux, FreeBSD, etc., the following environment variables are common. - -| var name | default value | comment | -|-------------------|------------------------------|----------------------------| -| `PATH` | `$BUILD_BIN_PATH:$PATH` | System PATH | -| `PKG_CONFIG_PATH` | `$BUILD_LIB_PATH/pkgconfig` | pkg-config search path | -| `PKG_CONFIG` | `$BUILD_BIN_PATH/pkg-config` | pkg-config executable path | - -## Library Environment variables (Unix only) +## Library environment variables (Unix only) Starting from 2.2.0, static-php-cli supports custom environment variables for all compilation dependent library commands of macOS, Linux, FreeBSD and other Unix systems. diff --git a/docs/zh/guide/env-vars.md b/docs/zh/guide/env-vars.md index 6c467542..7a42d32c 100644 --- a/docs/zh/guide/env-vars.md +++ b/docs/zh/guide/env-vars.md @@ -1,11 +1,21 @@ ---- -aside: false ---- - -# 环境变量列表 +# 环境变量 本页面的环境变量列表中所提到的所有环境变量都具有默认值，除非另有说明。你可以通过设置这些环境变量来覆盖默认值。 +## 环境变量列表 + +在 2.3.5 版本之后，我们将环境变量集中到了 `config/env.ini` 文件中，你可以通过修改这个文件来设置环境变量。 + +我们将 static-php-cli 支持的环境变量分为三种： + +- 全局内部环境变量：在 static-php-cli 启动后即声明，你可以在 static-php-cli 的内部使用 `getenv()` 来获取他们，也可以在启动 static-php-cli 前覆盖。 +- 固定环境变量：在 static-php-cli 启动后声明，你仅可使用 `getenv()` 获取，但无法通过 shell 脚本对其覆盖。 +- 配置文件环境变量：在 static-php-cli 构建前声明，你可以通过修改 `config/env.ini` 文件或通过 shell 脚本来设置这些环境变量。 + +你可以阅读 [config/env.ini](https://github.com/crazywhalecc/static-php-cli/blob/main/config/env.ini) 中每项参数的注释来了解其作用（仅限英文版）。 + +## 自定义环境变量 + 一般情况下，你不需要修改任何以下环境变量，因为它们已经被设置为最佳值。 但是，如果你有特殊需求，你可以通过设置这些环境变量来满足你的需求（比如你需要调试不同编译参数下的 PHP 性能表现）。 @@ -20,93 +30,11 @@ bin/spc build mbstring,pcntl --build-cli SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli ``` -## 通用环境变量 +或者，如果你需要长期修改某个环境变量，你可以通过修改 `config/env.ini` 文件来实现。 -通用环境变量是所有构建目标都可以使用的环境变量。 +`config/env.ini` 分为三段，其中 `[global]` 全局有效，`[windows]`、`[macos]`、`[linux]` 仅对应的操作系统有效。 -| var name | default value | comment | -|------------------------------|---------------------------|-----------------------------| -| `BUILD_ROOT_PATH` | `{pwd}/buildroot` | 编译目标的根目录 | -| `BUILD_LIB_PATH` | `{pwd}/buildroot/lib` | 编译依赖库的根目录 | -| `BUILD_INCLUDE_PATH` | `{pwd}/buildroot/include` | 编译依赖库的头文件目录 | -| `BUILD_BIN_PATH` | `{pwd}/buildroot/bin` | 编译依赖库的二进制文件目录 | -| `PKG_ROOT_PATH` | `{pwd}/pkgroot` | 闭源或预编译工具下载后安装的目录 | -| `SOURCE_PATH` | `{pwd}/source` | 编译项目的源码解压缩目录 | -| `DOWNLOAD_PATH` | `{pwd}/downloads` | 下载的文件存放目录 | -| `SPC_CONCURRENCY` | 取决于当前 CPU 核心数量 | 并行编译的数量 | -| `SPC_SKIP_PHP_VERSION_CHECK` | 空 | 设置为 `yes` 时，跳过扩展对 PHP 版本的检查 | - -## 系统特定变量 - -这些环境变量是特定于系统的，它们只在特定的系统上才会生效。 - -### Windows - -| var name | default value | comment | -|---------------------|-----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| -| `PHP_SDK_PATH` | `{pwd}\php-sdk-binary-tools` | PHP SDK 工具的安装目录 | -| `UPX_EXEC` | `$PKG_ROOT_PATH\bin\upx.exe` | UPX 压缩工具的路径 | -| `SPC_MICRO_PATCHES` | `static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream,cli_static` | 使用的 phpmicro [patches](https://github.com/easysoft/phpmicro/blob/master/patches/Readme.md) | - -### macOS - -| var name | default value | comment | -|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| -| `CC` | `clang` | C 编译器 | -| `CXX` | `clang++` | C++ 编译器 | -| `SPC_DEFAULT_C_FLAGS` | `--target=arm64-apple-darwin` 或 `--target=x86_64-apple-darwin` | 默认 C 编译标志（与 `CFLAGS` 不同） | -| `SPC_DEFAULT_CXX_FLAGS` | `--target=arm64-apple-darwin` 或 `--target=x86_64-apple-darwin` | 默认 C++ 编译标志（与 `CXXFLAGS` 不同） | -| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | 编译 PHP `buildconf` 命令前缀 | -| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | 编译 PHP `configure` 命令前缀 | -| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | 编译 PHP `make` 命令前缀 | -| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS -Werror=unknown-warning-option` | PHP `configure` 命令的 `CFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | PHP `configure` 命令的 `CPPFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | PHP `configure` 命令的 `LDFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os` 或 `-g -O0`（当使用 `--no-strip` 时为后者） | PHP `make` 命令的 `EXTRA_CFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | `-lresolv` | PHP `make` 命令的额外 `EXTRA_LIBS` 变量 | -| `SPC_MICRO_PATCHES` | `static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream,macos_iconv` | 使用的 phpmicro [patches](https://github.com/easysoft/phpmicro/blob/master/patches/Readme.md) | - -### Linux - -| var name | default value | comment | -|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| -| `UPX_EXEC` | `$PKG_ROOT_PATH/bin/upx` | UPX 压缩工具的路径 | -| `GNU_ARCH` | `x86_64` 或 `aarch64` | 当前环境的 CPU 架构 | -| `CC` | Alpine: `gcc`, Other: `$GNU_ARCH-linux-musl-gcc` | C 编译器 | -| `CXX` | Alpine: `g++`, Other: `$GNU_ARCH-linux-musl-g++` | C++ 编译器 | -| `AR` | Alpine: `ar`, Other: `$GNU_ARCH-linux-musl-ar` | 静态库工具 | -| `LD` | `ld.gold` | 链接器 | -| `PATH` | `/usr/local/musl/bin:/usr/local/musl/$GNU_ARCH-linux-musl/bin:$PATH` | 系统 PATH | -| `SPC_DEFAULT_C_FLAGS` | empty | 默认 C 编译标志 | -| `SPC_DEFAULT_CXX_FLAGS` | empty | 默认 C++ 编译标志 | -| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | 编译 PHP `buildconf` 命令前缀 | -| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `LD_LIBRARY_PATH={ld_lib_path} ./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | 编译 PHP `configure` 命令前缀 | -| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | 编译 PHP `make` 命令前缀 | -| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS` | PHP `configure` 命令的 `CFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | PHP `configure` 命令的 `CPPFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | PHP `configure` 命令的 `LDFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_CONFIGURE_LIBS` | `-ldl -lpthread` | PHP `configure` 命令的 `LIBS` 变量 | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os -fno-ident -fPIE` 或 `-g -O0 -fno-ident -fPIE`（当使用 `--no-strip` 时为后者） | PHP `make` 命令的 `EXTRA_CFLAGS` 变量 | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | empty | PHP `make` 命令的额外 `EXTRA_LIBS` 变量 | -| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM` | `-all-static`（当使用 `clang` 时：`-Xcompiler -fuse-ld=lld -all-static`） | `make` 命令的额外 `LDFLAGS` 变量（用于编译程序） | -| `SPC_NO_MUSL_PATH` | empty | 是否不插入 musl 工具链的 PATH（值为 `yes` 时不插入） | -| `SPC_MICRO_PATCHES` | `static_extensions_win32,cli_checks,disable_huge_page,vcruntime140,win32,zend_stream` | 使用的 phpmicro [patches](https://github.com/easysoft/phpmicro/blob/master/patches/Readme.md) | - -> `{ld_lib_path}` 值为 `/usr/local/musl/$GNU_ARCH-linux-musl/lib`。 - -### FreeBSD - -因 FreeBSD 系统的用户较少，我们暂时不提供 FreeBSD 系统的环境变量。 - -### Unix - -对于 macOS、Linux、FreeBSD 等 Unix 系统，以下环境变量是通用的。 - -| var name | default value | comment | -|-------------------|------------------------------|------------------| -| `PATH` | `$BUILD_BIN_PATH:$PATH` | 系统 PATH | -| `PKG_CONFIG_PATH` | `$BUILD_LIB_PATH/pkgconfig` | pkg-config 的搜索路径 | -| `PKG_CONFIG` | `$BUILD_BIN_PATH/pkg-config` | pkg-config 命令路径 | +例如，你需要修改编译 PHP 的 `./configure` 命令，你可以在 `config/env.ini` 文件中找到 `SPC_CMD_PREFIX_PHP_CONFIGURE` 环境变量，然后修改其值即可。 ## 编译依赖库的环境变量（仅限 Unix 系统） @@ -142,6 +70,7 @@ openssl_CFLAGS="-O0" | `ldap_LDFLAGS` | `-L$BUILD_LIB_PATH` | | `openssl_CFLAGS` | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty | | others... | empty | + ::: 下表是支持自定义以上三种变量的依赖库名称列表： @@ -165,5 +94,6 @@ openssl_CFLAGS="-O0" ::: tip 因为给每个库适配自定义环境变量是一项特别繁琐的工作，且大部分情况下你都不需要这些库的自定义环境变量，所以我们目前只支持了部分库的自定义环境变量。 -如果你需要自定义环境变量的库不在上方列表，可以通过 [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues) 来提出需求。 +如果你需要自定义环境变量的库不在上方列表，可以通过 [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues) +来提出需求。 :::