Skip to content
This repository was archived by the owner on Jul 1, 2024. It is now read-only.

Commit 6bc9480

Browse files
crazywhalecccrazywhalecc
authored
* update docs for crazywhalecc/static-php-cli#403 * add env vars english docs
1 parent d98232e commit 6bc9480

File tree

5 files changed

+929
-653
lines changed

5 files changed

+929
-653
lines changed

‎docs/.vitepress/sidebar.en.ts

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ export default {
99
{text: 'Extension List', link: '/en/guide/extensions'},
1010
{text: 'Extension Notes', link: '/en/guide/extension-notes'},
1111
{text: 'Command Generator', link: '/en/guide/cli-generator'},
12+
{text: 'Environment Variables', link: '/en/guide/env-vars', collapsed: true,},
1213
]
1314
},
1415
{

‎docs/.vitepress/sidebar.zh.ts

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ export default {
99
{text: '扩展列表', link: '/zh/guide/extensions'},
1010
{text: '扩展注意事项', link: '/zh/guide/extension-notes'},
1111
{text: '编译命令生成器', link: '/zh/guide/cli-generator'},
12+
{text: '环境变量列表', link: '/zh/guide/env-vars'},
1213
]
1314
},
1415
{

‎docs/en/guide/env-vars.md

+172
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
---
2+
aside: false
3+
---
4+
5+
# Environment variables
6+
7+
All environment variables mentioned in the list on this page have default values unless otherwise noted.
8+
You can override the default values by setting these environment variables.
9+
10+
Generally, you don't need to modify any of the following environment variables as they are already set to optimal values.
11+
However, if you have special needs, you can set these environment variables to meet your needs
12+
(for example, you need to debug PHP performance under different compilation parameters).
13+
14+
If you want to use custom environment variables, you can use the `export` command in the terminal or set the environment variables directly before the command, for example:
15+
16+
```shell
17+
# export first
18+
export SPC_CONCURRENCY=4
19+
bin/spc build mbstring,pcntl --build-cli
20+
21+
# or direct use
22+
SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli
23+
```
24+
25+
## General environment variables
26+
27+
General environment variables can be used by all build targets.
28+
29+
| var name | default value | comment |
30+
|----------------------|---------------------------|-------------------------------------------------|
31+
| `BUILD_ROOT_PATH` | `{pwd}/buildroot` | The root directory of the build target |
32+
| `BUILD_LIB_PATH` | `{pwd}/buildroot/lib` | The root directory of compilation libraries |
33+
| `BUILD_INCLUDE_PATH` | `{pwd}/buildroot/include` | Header file directory for compiling libraries |
34+
| `BUILD_BIN_PATH` | `{pwd}/buildroot/bin` | Compiled binary file directory |
35+
| `PKG_ROOT_PATH` | `{pwd}/pkgroot` | Directory where precompiled tools are installed |
36+
| `SOURCE_PATH` | `{pwd}/source` | The source code extract directory |
37+
| `DOWNLOAD_PATH` | `{pwd}/downloads` | Downloaded file directory |
38+
| `SPC_CONCURRENCY` | Depends on CPU cores | Number of parallel compilations |
39+
40+
## OS specific variables
41+
42+
These environment variables are system-specific and will only take effect on a specific OS.
43+
44+
### Windows
45+
46+
| var name | default value | comment |
47+
|----------------|------------------------------|---------------------------|
48+
| `PHP_SDK_PATH` | `{pwd}\php-sdk-binary-tools` | PHP SDK tools path |
49+
| `UPX_EXEC` | `$PKG_ROOT_PATH\bin\upx.exe` | UPX compression tool path |
50+
51+
### macOS
52+
53+
| var name | default value | comment |
54+
|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
55+
| `CC` | `clang` | C Compiler |
56+
| `CXX` | `clang++` | C++ Compiler |
57+
| `SPC_DEFAULT_C_FLAGS` | `--target=arm64-apple-darwin` or `--target=x86_64-apple-darwin` | Default C flags (not the same as `CFLAGS`) |
58+
| `SPC_DEFAULT_CXX_FLAGS` | `--target=arm64-apple-darwin` or `--target=x86_64-apple-darwin` | Default C flags (not the same as `CPPFLAGS`) |
59+
| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | PHP `buildconf` command prefix |
60+
| `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 |
61+
| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | PHP `make` command prefix |
62+
| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS -Werror=unknown-warning-option` | `CFLAGS` variable of PHP `configure` command |
63+
| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | `CPPFLAGS` variable of PHP `configure` command |
64+
| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | `LDFLAGS` variable of PHP `configure` command |
65+
| `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 |
66+
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | `-lresolv` | Extra `EXTRA_LIBS` variables for PHP `make` command |
67+
68+
### Linux
69+
70+
| var name | default value | comment |
71+
|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
72+
| `UPX_EXEC` | `$PKG_ROOT_PATH/bin/upx` | UPX compression tool path |
73+
| `GNU_ARCH` | `x86_64` or `aarch64` | CPU architecture |
74+
| `CC` | Alpine: `gcc`, Other: `$GNU_ARCH-linux-musl-gcc` | C Compiler |
75+
| `CXX` | Alpine: `g++`, Other: `$GNU_ARCH-linux-musl-g++` | C++ Compiler |
76+
| `AR` | Alpine: `ar`, Other: `$GNU_ARCH-linux-musl-ar` | Static library tools |
77+
| `LD` | `ld.gold` | Linker |
78+
| `PATH` | `/usr/local/musl/bin:/usr/local/musl/$GNU_ARCH-linux-musl/bin:$PATH` | System PATH |
79+
| `SPC_DEFAULT_C_FLAGS` | empty | Default C flags |
80+
| `SPC_DEFAULT_CXX_FLAGS` | empty | Default C++ flags |
81+
| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | PHP `buildconf` command prefix |
82+
| `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 |
83+
| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | PHP `make` command prefix |
84+
| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS` | `CFLAGS` variable of PHP `configure` command |
85+
| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | `CPPFLAGS` variable of PHP `configure` command |
86+
| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | `LDFLAGS` variable of PHP `configure` command |
87+
| `SPC_CMD_VAR_PHP_CONFIGURE_LIBS` | `-ldl -lpthread` | `LIBS` variable of PHP `configure` command |
88+
| `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 |
89+
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | empty | Extra `EXTRA_LIBS` variables for PHP `make` command |
90+
| `SPC_CMD_VAR_MAKE_EXTRA_LDFLAGS_PROGRAM` | `-all-static` (when using `clang`: `-Xcompiler -fuse-ld=lld -all-static`) | Additional `LDFLAGS` variable for `make` command |
91+
92+
> `{ld_lib_path}` value is `/usr/local/musl/$GNU_ARCH-linux-musl/lib`。
93+
94+
### FreeBSD
95+
96+
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.
97+
98+
### Unix
99+
100+
For Unix systems such as macOS, Linux, FreeBSD, etc., the following environment variables are common.
101+
102+
| var name | default value | comment |
103+
|-------------------|------------------------------|----------------------------|
104+
| `PATH` | `$BUILD_BIN_PATH:$PATH` | System PATH |
105+
| `PKG_CONFIG_PATH` | `$BUILD_LIB_PATH/pkgconfig` | pkg-config search path |
106+
| `PKG_CONFIG` | `$BUILD_BIN_PATH/pkg-config` | pkg-config executable path |
107+
108+
## Library Environment variables (Unix only)
109+
110+
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.
111+
112+
In this way, you can adjust the behavior of compiling dependent libraries through environment variables at any time.
113+
For example, you can set the optimization parameters for compiling the xxx library through `xxx_CFLAGS=-O0`.
114+
115+
Of course, not every library supports the injection of environment variables.
116+
We currently provide three wildcard environment variables with the suffixes:
117+
118+
- `_CFLAGS`: CFLAGS for the compiler
119+
- `_LDFLAGS`: LDFLAGS for the linker
120+
- `_LIBS`: LIBS for the linker
121+
122+
The prefix is the name of the dependent library, and the specific name of the library is subject to `lib.json`.
123+
Among them, the library name with `-` needs to replace `-` with `_`.
124+
125+
Here is an example of an optimization option that replaces the openssl library compilation:
126+
127+
```shell
128+
openssl_CFLAGS="-O0"
129+
```
130+
131+
The library name uses the same name listed in `lib.json` and is case-sensitive.
132+
133+
::: tip
134+
When no relevant environment variables are specified, except for the following variables, the remaining values are empty by default:
135+
136+
| var name | var default value |
137+
|-----------------------|-------------------------------------------------------------------------------------------------|
138+
| `pkg_config_CFLAGS` | macOS: `$SPC_DEFAULT_C_FLAGS -Wimplicit-function-declaration -Wno-int-conversion`, Other: empty |
139+
| `pkg_config_LDFLAGS` | Linux: `--static`, Other: empty |
140+
| `imagemagick_LDFLAGS` | Linux: `-static`, Other: empty |
141+
| `imagemagick_LIBS` | macOS: `-liconv`, Other: empty |
142+
| `ldap_LDFLAGS` | `-L$BUILD_LIB_PATH` |
143+
| `openssl_CFLAGS` | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty |
144+
| others... | empty |
145+
:::
146+
147+
The following table is a list of library names that support customizing the above three variables:
148+
149+
| lib name |
150+
|-------------|
151+
| brotli |
152+
| bzip |
153+
| curl |
154+
| freetype |
155+
| gettext |
156+
| gmp |
157+
| imagemagick |
158+
| ldap |
159+
| libargon2 |
160+
| libavif |
161+
| libcares |
162+
| libevent |
163+
| openssl |
164+
165+
::: tip
166+
Because adapting custom environment variables to each library is a particularly tedious task,
167+
and in most cases you do not need custom environment variables for these libraries,
168+
so we currently only support custom environment variables for some libraries.
169+
170+
If the library you need to customize environment variables is not listed above,
171+
you can submit your request through [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues).
172+
:::

0 commit comments

Comments
 (0)