crazywhalecc/static-php-cli
1
0
Fork 0
mirror of https://github.com/crazywhalecc/static-php-cli.git synced 2026-07-03 23:05:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add build from config support (craft command)

Browse Source
This commit is contained in:
crazywhalecc
2025-04-24 14:18:39 +08:00
parent 455ed7d503
commit bd341db54a
19 changed files with 924 additions and 327 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
docs/.vitepress/components/CliGenerator.vue
View File

@@ -175,6 +175,12 @@
{{ buildCommandString }}
</div>
</div>
<div class="command-container">
<b>craft.yml</b>
<div id="craft-cmd" class="command-preview pre">
{{ craftCommandString }}
</div>
</div>
</div>
</template>
@@ -499,6 +505,38 @@ const buildCommandString = computed(() => {
return `${spcCommand.value} build ${buildCommand.value} "${extList.value}"${additionalLibs.value}${debug.value ? ' --debug' : ''}${zts.value ? ' --enable-zts' : ''}${enableUPX.value ? ' --with-upx-pack' : ''}${displayINI.value}`;
});
const craftCommandString = computed(() => {
let str = `php-version: ${selectedPhpVersion.value}\n`;
str += `extensions: "${extList.value}"\n`;
if (checkedTargets.value.join(',') === 'all') {
str += 'sapi: ' + ['cli', 'fpm', 'micro', 'embed'].join(',') + '\n';
} else {
str += `sapi: ${checkedTargets.value.join(',')}\n`;
}
if (additionalLibs.value) {
str += `libs: ${additionalLibs.value.replace('--with-libs="', '').replace('"', '').trim()}\n`;
}
if (debug.value) {
str += 'debug: true\n';
}
str += '{{position_hold}}';
if (enableUPX.value) {
str += ' with-upx-pack: true\n';
}
if (zts.value) {
str += ' enable-zts: true\n';
}
if (preBuilt.value) {
str += ' prefer-pre-built: true\n';
}
if (!str.endsWith('{{position_hold}}')) {
str = str.replace('{{position_hold}}', 'build-options:\n');
} else {
str = str.replace('{{position_hold}}', '');
}
return str;
});
const calculateExtLibDepends = (input) => {
const result = new Set();
@@ -617,6 +655,12 @@ h2 {
overflow-wrap: break-word;
}
.pre {
white-space: pre-wrap;
word-break: break-word;
overflow-wrap: break-word;
}
.option-line {
padding: 4px 8px;
}

109
docs/.vitepress/sidebar.en.ts
View File

@@ -1,56 +1,57 @@
export default {
'/en/guide/': [
{
text: 'Basic Build Guides',
items: [
{text: 'Guide', link: '/en/guide/'},
{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: '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 GNU libc', link: '/en/guide/build-with-glibc'},
],
}
],
'/en/develop/': [
{
text: 'Development',
items: [
{text: 'Get Started', link: '/en/develop/'},
{text: 'Project Structure', link: '/en/develop/structure'},
{text: 'PHP Source Modification', link: '/en/develop/php-src-changes'},
],
},
{
text: 'Module',
items: [
{text: 'Doctor ', link: '/en/develop/doctor-module'},
{text: 'Source', link: '/en/develop/source-module'},
]
},
{
text: 'Extra',
items: [
{text: 'Compilation Tools', link: '/en/develop/system-build-tools'},
]
}
],
'/en/contributing/': [
{
text: 'Contributing',
items: [
{text: 'Contributing', link: '/en/contributing/'},
],
}
],
'/en/guide/': [
{
text: 'Basic Build Guides',
items: [
{text: 'Guide', link: '/en/guide/'},
{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: '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 GNU libc', link: '/en/guide/build-with-glibc'},
],
}
],
'/en/develop/': [
{
text: 'Development',
items: [
{text: 'Get Started', link: '/en/develop/'},
{text: 'Project Structure', link: '/en/develop/structure'},
{text: 'PHP Source Modification', link: '/en/develop/php-src-changes'},
],
},
{
text: 'Module',
items: [
{text: 'Doctor ', link: '/en/develop/doctor-module'},
{text: 'Source', link: '/en/develop/source-module'},
]
},
{
text: 'Extra',
items: [
{text: 'Compilation Tools', link: '/en/develop/system-build-tools'},
{text: 'craft.yml Configuration', link: '/zh/develop/craft-yml'},
]
}
],
'/en/contributing/': [
{
text: 'Contributing',
items: [
{text: 'Contributing', link: '/en/contributing/'},
],
}
],
};

109
docs/.vitepress/sidebar.zh.ts
View File

@@ -1,56 +1,57 @@
export default {
'/zh/guide/': [
{
text: '构建指南',
items: [
{text: '指南', link: '/zh/guide/'},
{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'},
{text: '环境变量列表', link: '/zh/guide/env-vars'},
{text: '依赖关系图表', link: '/zh/guide/deps-map'},
]
},
{
text: '扩展构建指南',
items: [
{text: '故障排除', link: '/zh/guide/troubleshooting'},
{text: '在 Windows 上构建', link: '/zh/guide/build-on-windows'},
{text: '构建 GNU libc 兼容的二进制', link: '/zh/guide/build-with-glibc'},
],
}
],
'/zh/develop/': [
{
text: '开发指南',
items: [
{ text: '开发简介', link: '/zh/develop/' },
{ text: '项目结构简介', link: '/zh/develop/structure' },
{text: '对 PHP 源码的修改', link: '/zh/develop/php-src-changes'},
],
},
{
text: '模块',
items: [
{ text: 'Doctor 环境检查工具', link: '/zh/develop/doctor-module' },
{ text: '资源模块', link: '/zh/develop/source-module' },
]
},
{
text: '其他',
items: [
{text: '系统编译工具', link: '/zh/develop/system-build-tools'},
]
}
],
'/zh/contributing/': [
{
text: '贡献指南',
items: [
{text: '贡献指南', link: '/zh/contributing/'},
],
}
],
'/zh/guide/': [
{
text: '构建指南',
items: [
{text: '指南', link: '/zh/guide/'},
{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'},
{text: '环境变量列表', link: '/zh/guide/env-vars'},
{text: '依赖关系图表', link: '/zh/guide/deps-map'},
]
},
{
text: '扩展构建指南',
items: [
{text: '故障排除', link: '/zh/guide/troubleshooting'},
{text: '在 Windows 上构建', link: '/zh/guide/build-on-windows'},
{text: '构建 GNU libc 兼容的二进制', link: '/zh/guide/build-with-glibc'},
],
}
],
'/zh/develop/': [
{
text: '开发指南',
items: [
{text: '开发简介', link: '/zh/develop/'},
{text: '项目结构简介', link: '/zh/develop/structure'},
{text: '对 PHP 源码的修改', link: '/zh/develop/php-src-changes'},
],
},
{
text: '模块',
items: [
{text: 'Doctor 环境检查工具', link: '/zh/develop/doctor-module'},
{text: '资源模块', link: '/zh/develop/source-module'},
]
},
{
text: '其他',
items: [
{text: '系统编译工具', link: '/zh/develop/system-build-tools'},
{text: 'craft.yml 配置详解', link: '/zh/develop/craft-yml'},
]
}
],
'/zh/contributing/': [
{
text: '贡献指南',
items: [
{text: '贡献指南', link: '/zh/contributing/'},
],
}
],
};

67
docs/deps-craft-yml.md Normal file
View File

@@ -0,0 +1,67 @@
```yaml
# PHP version to build (default: 8.4)
php-version: 8.4
# [REQUIRED] Static PHP extensions to build (list or comma-separated are both accepted)
extensions: bcmath,fileinfo,phar,zlib,sodium,posix,pcntl
# Extra libraries to build (list or comma-separated are both accepted)
libs: [ ]
# [REQUIRED] Build SAPIs (list or comma-separated are both accepted)
sapi: cli,micro,fpm
# Show full console output (default: false)
debug: false
# Build options (same as `build` command options, all options are optional)
build-options:
# Before build, remove all old build files and sources (default: false)
with-clean: false
# Build with all suggested libraries (default: false)
with-suggested-libs: false
# Build with all suggested extensions (default: false)
with-suggested-exts: false
# Build extra shared extensions (list or comma-separated are both accepted)
build-shared: [ ]
# Build without stripping the binary (default: false)
no-strip: false
# Disable Opcache JIT (default: false)
disable-opcache-jit: false
# PHP configuration options (same as --with-config-file-path)
with-config-file-path: ""
# PHP configuration options (same as --with-config-file-scan-dir)
with-config-file-scan-dir: ""
# Hardcoded INI options for cli and micro SAPI (e.g. "memory_limit=4G", list accepted)
with-hardcoded-ini: [ ]
# Pretend micro SAPI as cli SAPI to avoid some frameworks to limit the usage of micro SAPI
with-micro-fake-cli: false
# Additional patch point injection files (e.g. "path/to/patch.php", list accepted)
with-added-patch: [ ]
# Ignore micro extension tests (if you are using micro SAPI, default: false)
without-micro-ext-test: false
# UPX pack the binary (default: false)
with-upx-pack: false
# Set the micro.exe program icon (only for Windows, default: "")
with-micro-logo: ""
# Set micro SAPI as win32 mode, without this, micro SAPI will be compiled as a console application (only for Windows, default: false)
enable-micro-win32: false
# Download options
download-options:
# Use custom url for specified sources, format: "{source-name}:{url}" (e.g. "php-src:https://example.com/php-8.4.0.tar.gz")
custom-url: [ ]
# Use custom git repo for specified sources, format: "{source-name}:{branch}:{url}" (e.g. "php-src:master:https://github.com/php/php-src.git")
custom-git: [ ]
# Retries count for downloading sources (default: 5)
retry: 5
# Use pre-built libraries if available (default: false)
prefer-pre-built: true
# Do not download from alternative sources (default: false)
no-alt: false
craft-options:
doctor: true
download: true
build: true
# Extra environment variables
extra-env:
# e.g. Use github token to avoid rate limit
GITHUB_TOKEN: your-github-token
```

7
docs/en/develop/craft-yml.md Normal file
View File

@@ -0,0 +1,7 @@
---
aside: false
---
# craft.yml Configuration
<!--@include: ../../deps-craft-yml.md-->

72
docs/en/guide/manual-build.md
View File

@@ -1,3 +1,7 @@
---
outline: 'deep'
---
# Build (Linux, macOS, FreeBSD)
This section covers the build process for Linux, macOS, and FreeBSD. If you want to build on Windows,
@@ -133,7 +137,47 @@ and then install the latest version of PHP and tokenizer, XML, and phar extensio
Older versions of Debian may have an older (<= 7.4) version of PHP installed by default, it is recommended to upgrade Debian first.
:::
## Command - download
## Build with craft (recommended)
Using `bin/spc craft`, you can use a configuration file and a command to automatically check the environment, download source code, build dependency libraries, build PHP and extensions, etc.
You need to write a `craft.yml` file and save it in the current working directory. `craft.yml` can be generated by [command generator](./cli-generator) or written manually.
For manual writing, please refer to the comments in [craft.yml configuration](../develop/craft-yml.md) to write it.
Let's assume that you compile an extension combination and choose PHP 8.4, outputting `cli` and `fpm`:
```yaml
# path/to/craft.yml
php-version: 8.4
extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
sapi:
- cli
- fpm
```
Then use the `bin/spc craft` command to compile:
```bash
bin/spc craft --debug
```
If the build is successful, you will see the `buildroot/bin` directory in the current directory, which contains the compiled PHP binary file, or the corresponding SAPI.
- cli: The build result is `buildroot/bin/php.exe` on Windows and `buildroot/bin/php` on other platforms.
- fpm: The build result is `buildroot/bin/php-fpm`.
- micro: The build result is `buildroot/bin/micro.sfx`. If you need to further package it with PHP code, please refer to [Packaging micro binary](./manual-build#command-micro-combine).
- embed: See [Using embed](./manual-build#embed-usage).
If the build fails, you can use the `--debug` parameter to view detailed error information,
or use the `--with-clean` to clear the old compilation results and recompile.
If the build still fails to use the above method, please submit an issue and attach your `craft.yml` and `craft.log`.
## Step-by-step build command
If you have customized requirements, or the need to download and compile PHP and dependent libraries separately, you can use the `bin/spc` command to execute step by step.
### Command download - Download dependency packages
Use the command `bin/spc download` to download the source code required for compilation,
including php-src and the source code of various dependent libraries.
@@ -217,7 +261,7 @@ bin/spc download --for-extensions=redis -G "php-src:master:https://github.com/ph
bin/spc download --for-extensions=swoole -G "swoole:master:https://github.com/swoole/swoole-src.git"
```
## Command - doctor
### Command - doctor
If you can run `bin/spc` normally but cannot compile static PHP or dependent libraries normally,
you can run `bin/spc doctor` first to check whether the system itself lacks dependencies.
@@ -230,13 +274,13 @@ bin/spc doctor
bin/spc doctor --auto-fix
```
## Command - build
### Command - build
Use the build command to start building the static php binary.
Before executing the `bin/spc build` command, be sure to use the `download` command to download sources.
It is recommended to use `doctor` to check the environment.
### Basic build
#### Basic build
You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add,
and then use the command `bin/spc build` to compile.
@@ -283,16 +327,7 @@ bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
### Debug
If you encounter problems during the compilation process, or want to view each executing shell command,
you can use `--debug` to enable debug mode and view all terminal logs:
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
### Build Options
#### Build Options
During the compilation process, in some special cases,
the compiler and the content of the compilation directory need to be intervened.
@@ -322,6 +357,15 @@ For hardcoding INI options, it works for cli, micro, embed sapi. Here is a simpl
bin/spc build bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
```
## Debug
If you encounter problems during the compilation process, or want to view each executing shell command,
you can use `--debug` to enable debug mode and view all terminal logs:
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
## Command - micro:combine
Use the `micro:combine` command to build the compiled `micro.sfx` and your code (`.php` or `.phar` file) into an executable binary.

7
docs/zh/develop/craft-yml.md Normal file
View File

@@ -0,0 +1,7 @@
---
aside: false
---
# craft.yml 配置
<!--@include: ../../deps-craft-yml.md-->

68
docs/zh/guide/manual-build.md
View File

@@ -1,3 +1,7 @@
---
outline: 'deep'
---
# 本地构建（Linux、macOS、FreeBSD）
本章节为 Linux、macOS、FreeBSD 的构建过程，如果你要在 Windows 上构建，请到 [在 Windows 上构建](./build-on-windows)。
@@ -112,7 +116,45 @@ sudo apt install php-cli composer php-tokenizer
较老版本的 Debian 默认安装的可能为旧版本（<= 8.3）版本的 PHP，建议先升级 Debian 或使用 Docker 或自带的静态二进制环境。
:::
## 命令 download - 下载依赖包
## 使用 craft 构建（推荐）
使用 `bin/spc craft` 可以使用一个配置文件，一个命令实现自动检查环境、下载源代码、构建依赖库、构建 PHP 及扩展等。
你需要编写一个 `craft.yml` 文件，存放在当前工作目录下。`craft.yml` 可以由 [命令生成器](./cli-generator) 生成，或者手动编写。
手动编写可参考 [craft.yml 配置](../develop/craft-yml.md) 中的注释来编写。我们下面假设你编译一个扩展组合，并选用 PHP 8.4，输出 `cli` 和 `fpm`：
```yaml
# path/to/craft.yml
php-version: 8.4
extensions: bcmath,posix,phar,zlib,openssl,curl,fileinfo,tokenizer
sapi:
- cli
- fpm
```
然后使用 `bin/spc craft` 命令来编译：
```bash
bin/spc craft --debug
```
如果构建成功，你会在当前目录下看到 `buildroot/bin` 目录，里面包含了编译好的 PHP 二进制文件，或相应的 SAPI。
- cli: Windows 下构建结果为 `buildroot/bin/php.exe`，其他平台为 `buildroot/bin/php`。
- fpm: 构建结果为 `buildroot/bin/php-fpm`。
- micro: 构建结果为 `buildroot/bin/micro.sfx`，如需进一步与 PHP 代码打包，请查看 [打包 micro 二进制](./manual-build#命令-micro-combine-打包-micro-二进制)。
- embed: 参见 [embed 使用](./manual-build#embed-使用)。
如果中途构建出错，你可以使用 `--debug` 参数查看详细的错误信息，或者使用 `--with-clean` 参数清除旧的编译结果，重新编译。
如使用以上方式仍构建失败，请提交一个 issue，附上你的 `craft.yml`、`craft.log`。
## 分步构建命令
如果你有定制化需求，或分开下载、编译 PHP 和依赖库的需求，可以使用 `bin/spc` 命令分步执行。
### 命令 download - 下载依赖包
使用命令 `bin/spc download` 可以下载编译需要的源代码，包括 php-src 以及依赖的各种库的源码。
@@ -184,7 +226,7 @@ bin/spc download --for-extensions=redis,phar -G "php-src:master:https://github.c
bin/spc download --for-extensions=swoole -G "swoole:master:https://github.com/swoole/swoole-src.git"
```
## 命令 doctor - 环境检查
### 命令 doctor - 环境检查
如果你可以正常运行 `bin/spc` 但无法正常编译静态的 PHP 或依赖库，可以先运行 `bin/spc doctor` 检查系统自身是否缺少依赖。
@@ -196,11 +238,11 @@ bin/spc doctor
bin/spc doctor --auto-fix
```
## 命令 build - 编译 PHP
### 命令 build - 编译 PHP
使用 build 命令可以开始构建静态 php 二进制，在执行 `bin/spc build` 命令前，务必先使用 `download` 命令下载资源，建议使用 `doctor` 检查环境。
### 基本用法
#### 基本用法
你需要先到 [扩展列表](./extensions) 或 [命令生成器](./cli-generator) 选择你要加入的扩展，然后使用命令 `bin/spc build` 进行编译。你需要指定一个编译目标，从如下参数中选择：
@@ -244,15 +286,7 @@ bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
### 调试
如果你在编译过程中遇到了问题，或者想查看每个执行的 shell 命令，可以使用 `--debug` 开启 debug 模式，查看所有终端日志：
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
### 编译运行选项
#### 编译运行选项
在编译过程中，有些特殊情况需要对编译器、编译目录的内容进行干预，可以尝试使用以下命令：
@@ -340,6 +374,14 @@ memory_limit=1G
如果要打包 phar，只需要将 `a.php` 替换为打包好的 phar 文件即可。但要注意，phar 下的 micro.sfx 需要额外注意路径问题，见 [Developing - Phar 路径问题](../develop/structure#phar-应用目录问题)
## 调试
如果你在编译过程中遇到了问题，或者想查看每个执行的 shell 命令，可以使用 `--debug` 开启 debug 模式，查看所有终端日志：
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
## 命令 extract - 手动解压某个库
使用命令 `bin/spc extract` 可以解包和拷贝编译需要的源代码，包括 php-src 以及依赖的各种库的源码（需要自己指定要解包的库名）。