Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@crazywhalecc
crazywhalecc committed Jul 13, 2024
1 parent 4dbbf05 commit 758b697
Show file tree
Hide file tree
Showing 9 changed files with 159 additions and 76 deletions.
20 changes: 13 additions & 7 deletions README-zh.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,15 +43,17 @@ static-php-cli（简称 `spc`）有许多特性：

如果你不想自行编译 PHP，可以从本项目现有的示例 Action 下载 Artifact，也可以从自托管的服务器下载。

- [扩展组合 - common](https://dl.static-php.dev/static-php-cli/common/)：common 组合包含了约 [30+](https://dl.static-php.dev/static-php-cli/common/README.txt) 个常用扩展，体积为 7.5MB 左右。
- [扩展组合 - bulk](https://dl.static-php.dev/static-php-cli/bulk/)：bulk 组合包含了 [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt) 个扩展，体积为 25MB 左右。
- [扩展组合 - minimal](https://dl.static-php.dev/static-php-cli/minimal/)：minimal 组合包含了 [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt) 个扩展，体积为 3MB 左右。
| 组合名称 | 组合扩展数 | 系统 | 备注 |
|---------------------------------------------------------------------|----------------------------------------------------------------------------|-------------|--------------|
| [common](https://dl.static-php.dev/static-php-cli/common/) | [30+](https://dl.static-php.dev/static-php-cli/common/README.txt) | Linux/macOS | 体积为 7.5MB 左右 |
| [bulk](https://dl.static-php.dev/static-php-cli/bulk/) | [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt) | Linux/macOS | 体积为 25MB 左右 |
| [minimal](https://dl.static-php.dev/static-php-cli/minimal/) | [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt) | Linux/macOS | 体积为 3MB 左右 |
| [spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min) | [5](https://dl.static-php.dev/static-php-cli/windows/spc-min/README.txt) | Windows | 体积为 3MB 左右 |
| [spc-max](https://dl.static-php.dev/static-php-cli/windows/spc-max) | [40+](https://dl.static-php.dev/static-php-cli/windows/spc-max/README.txt) | Windows | 体积为 8.5MB 左右 |

> Linux 和 Windows 默认启用了 UPX 压缩，可减小 30~50% 的 PHP 二进制体积。
> macOS 当前不支持 UPX，所以上述预编译的 macOS 版本体积可能较大。
对于 Windows 系统，目前支持的扩展较少，故仅提供 SPC 自身运行的最小扩展组合的 `cli` 和 `micro`：[扩展组合 - spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/)。

## 使用 static-php-cli 构建 PHP

### 编译环境需求
Expand Down Expand Up @@ -110,7 +112,7 @@ static-php-cli（简称 `spc`）有许多特性：

如果你选择了 `debug`，则会在构建时输出所有日志，包括编译的日志，以供排查错误。

### 本地构建（使用 spc 二进制）
### 本地构建（使用 spc 二进制，推荐）

该项目提供了 static-php-cli 的二进制文件：`spc`。
您可以使用 `spc` 二进制文件，无需安装任何运行时（用起来就像 golang 程序）。
Expand Down Expand Up @@ -144,6 +146,8 @@ chmod +x ./spc

### 本地构建（使用 git 源码）

如果你需要修改 static-php-cli 源码，或者使用 spc 二进制构建有问题，你可以使用 git 源码下载 static-php-cli。

```bash
# clone 仓库即可
git clone https://github.com/crazywhalecc/static-php-cli.git
Expand Down Expand Up @@ -177,14 +181,16 @@ bin/spc --version
./bin/spc download --all
# 只拉取编译指定扩展需要的所有依赖（推荐）
./bin/spc download --for-extensions="openssl,pcntl,mbstring,pdo_sqlite"
# 下载依赖时，优先下载有预编译的库（节省编译依赖的时间）
./bin/spc download --for-extensions="openssl,curl,mbstring,mbregex" --prefer-pre-built
# 下载编译不同版本的 PHP (--with-php=x.y，推荐 7.3 ~ 8.3)
./bin/spc download --for-extensions="openssl,curl,mbstring" --with-php=8.1

# 构建包含 bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl 扩展的 php-cli 和 micro.sfx
./bin/spc build "bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl" --build-cli --build-micro
# 编译线程安全版本 (--enable-zts)
./bin/spc build "curl,phar" --enable-zts --build-cli
# 编译后使用 UPX 减小可执行文件体积 (--with-upx-pack) (至少压缩至原来的 30~50%)
# 编译后使用 UPX 减小可执行文件体积 (仅 Linux、Windows 可用) (至少压缩至原来的 30~50%)
./bin/spc build "curl,phar" --enable-zts --build-cli --with-upx-pack
```

Expand Down
23 changes: 15 additions & 8 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,17 @@ If you don't want to build or want to test first, you can download example pre-c
Below are several precompiled static-php binaries with different extension combinations,
which can be downloaded directly according to your needs.

- [Extension-Combination - common](https://dl.static-php.dev/static-php-cli/common/): `common` contains about [30+](https://dl.static-php.dev/static-php-cli/common/README.txt) commonly used extensions, and the size is about 7.5MB.
- [Extension-Combination - bulk](https://dl.static-php.dev/static-php-cli/bulk/): `bulk` contains [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt) extensions and is about 25MB in size.
- [Extension-Combination - minimal](https://dl.static-php.dev/static-php-cli/minimal/): `minimal` contains [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt) extensions and is about 3MB in size.
| Combination | Extension Count | OS | Comment |
|----------------------------------------------------------------------|---------------------------------------------------------------------------|--------------|--------------------------------|
| [common](https://dl.static-php.dev/static-php-cli/common/) | [30+](https://dl.static-php.dev/static-php-cli/common/README.txt) | Linux, macOS | The binary size is about 7.5MB |
| [bulk](https://dl.static-php.dev/static-php-cli/bulk/) | [50+](https://dl.static-php.dev/static-php-cli/bulk/README.txt) | Linux, macOS | The binary size is about 25MB |
| [minimal](https://dl.static-php.dev/static-php-cli/minimal/) | [5](https://dl.static-php.dev/static-php-cli/minimal/README.txt) | Linux, macOS | The binary size is about 3MB |
| [spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/) | [5](https://dl.static-php.dev/static-php-cli/windows/spc-min/README.txt) | Windows | The binary size is about 3MB |
| [spc-max](https://dl.static-php.dev/static-php-cli/windows/spc-max/) | [10](https://dl.static-php.dev/static-php-cli/windows/spc-max/README.txt) | Windows | The binary size is about 8.5MB |

> Linux and Windows supports UPX compression for binaries, which can reduce the size of the binary by 30% to 50%.
> macOS does not support UPX compression, so the size of the pre-built binaries for mac is larger.
For Windows systems, there are currently fewer extensions supported,
so only `cli` and `micro` that run the minimum extension combination of SPC itself are provided: [Extension-Combination - spc-min](https://dl.static-php.dev/static-php-cli/windows/spc-min/).

## Build

### Compilation Requirements
Expand Down Expand Up @@ -97,6 +98,7 @@ Currently supported PHP versions for compilation:
| 8.1 | :heavy_check_mark: | PHP official has security fixes only |
| 8.2 | :heavy_check_mark: | |
| 8.3 | :heavy_check_mark: | |
| 8.4 | :x: | WIP |

### Supported Extensions

Expand All @@ -121,7 +123,7 @@ and at the same time define the extensions to be compiled by yourself.

If you enable `debug`, all logs will be output at build time, including compiled logs, for troubleshooting.

### Build Locally (using SPC binary)
### Build Locally (using SPC binary, recommended)

This project provides a binary file of static-php-cli: `spc`.
You can use `spc` binary instead of installing any runtime like golang app.
Expand Down Expand Up @@ -155,6 +157,9 @@ Self-hosted `spc` is built by GitHub Actions, you can also download from Actions

### Build Locally (using git source)

If you need to modify the static-php-cli source code, or have problems using the spc binary build,
you can download static-php-cli using the git source code.

```bash
# just clone me!
git clone https://github.com/crazywhalecc/static-php-cli.git
Expand Down Expand Up @@ -188,14 +193,16 @@ Basic usage for building php with some extensions:
./bin/spc download --all
# only fetch necessary sources by needed extensions (recommended)
./bin/spc download --for-extensions="openssl,pcntl,mbstring,pdo_sqlite"
# download pre-built libraries first (save time for compiling dependencies)
./bin/spc download --for-extensions="openssl,curl,mbstring,mbregex" --prefer-pre-built
# download different PHP version (--with-php=x.y, recommend 7.3 ~ 8.3)
./bin/spc download --for-extensions="openssl,curl,mbstring" --with-php=8.1

# with bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl extension, build both CLI and phpmicro SAPI
./bin/spc build "bcmath,openssl,tokenizer,sqlite3,pdo_sqlite,ftp,curl" --build-cli --build-micro
# build thread-safe (ZTS) version (--enable-zts)
./bin/spc build "curl,phar" --enable-zts --build-cli
# build, pack executable with UPX (--with-upx-pack) (reduce binary size for 30~50%)
# build, pack executable with UPX (linux and windows only) (reduce binary size for 30~50%)
./bin/spc build "curl,phar" --enable-zts --build-cli --with-upx-pack
```

Expand Down
153 changes: 95 additions & 58 deletions docs/.vitepress/components/CliGenerator.vue
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,11 @@
<h2>{{ I18N[lang].selectExt }}{{ checkedExts.length > 0 ? (' (' + checkedExts.length + ')') : '' }}</h2>
<div class="box">
<div v-for="(item, index) in ext" class="ext-item">
<input type="checkbox" :id="index" :value="index" v-model="checkedExts" :disabled="extDisableList.indexOf(index) !== -1">
<label :for="index">{{ index }}</label>
<span v-if="isSupported(index, selectedSystem)">
<input type="checkbox" :id="index" :value="index" v-model="checkedExts" :disabled="extDisableList.indexOf(index) !== -1">
<label :for="index">{{ index }}</label>
</span>

</div>
</div>
<div class="my-btn" v-if="selectedSystem !== 'windows'" @click="selectCommon">{{ I18N[lang].selectCommon }}</div>
Expand Down Expand Up @@ -46,59 +49,80 @@
<p>{{ I18N[lang].windowsSAPIUnavailable }}</p>
</div>
<h2>{{ I18N[lang].buildOptions }}</h2>
<div class="option-line">
<span class="option-title">{{ I18N[lang].buildEnvironment }}</span>
<select v-model="selectedEnv">
<option value="native">{{ I18N[lang].buildEnvNative }}</option>
<option value="spc">{{ I18N[lang].buildEnvSpc }}</option>
<option value="docker" v-if="selectedSystem !== 'windows'">{{ I18N[lang].buildEnvDocker }}</option>
</select>
</div>
<div v-if="selectedEnv === 'spc'" class="option-line">
<span class="option-title">{{ I18N[lang].selectedArch }}</span>
<select v-model="selectedArch">
<option value="x86_64">x86_64 (amd64)</option>
<option value="aarch64" v-if="selectedSystem !== 'windows'">aarch64 (arm64)</option>
</select>
</div>
<div class="option-line">
<span class="option-title">{{ I18N[lang].downloadPhpVersion }}</span>
<select v-model="selectedPhpVersion">
<option v-for="item in availablePhpVersions" :value="item">{{ item }}</option>
</select>
</div>
<div class="option-line">
<span class="option-title">{{ I18N[lang].useDebug }}</span>
<input type="radio" id="debug-yes" :value="1" v-model="debug" />
<label for="debug-yes">{{ I18N[lang].yes }}</label>

<input type="radio" id="debug-no" :value="0" v-model="debug" />
<label for="debug-no">{{ I18N[lang].no }}</label>
</div>
<div class="option-line">
<span class="option-title">{{ I18N[lang].useZTS }}</span>
<input type="radio" id="zts-yes" :value="1" v-model="zts" />
<label for="zts-yes">{{ I18N[lang].yes }}</label>
<!-- Refactor all build options in table -->
<table>
<!-- buildEnvironment -->
<tr>
<td>{{ I18N[lang].buildEnvironment }}</td>
<td>
<select v-model="selectedEnv">
<option value="native">{{ I18N[lang].buildEnvNative }}</option>
<option value="spc">{{ I18N[lang].buildEnvSpc }}</option>
<option value="docker" v-if="selectedSystem !== 'windows'">{{ I18N[lang].buildEnvDocker }}</option>
</select>
</td>
</tr>
<!-- Download PHP version -->
<tr>
<td>{{ I18N[lang].downloadPhpVersion }}</td>
<td>
<select v-model="selectedPhpVersion">
<option v-for="item in availablePhpVersions" :value="item">{{ item }}</option>
</select>
</td>
</tr>
<!-- Enable debug message -->
<tr>
<td>{{ I18N[lang].useDebug }}</td>
<td>
<input type="radio" id="debug-yes" :value="1" v-model="debug" />
<label for="debug-yes">{{ I18N[lang].yes }}</label>
<input type="radio" id="debug-no" :value="0" v-model="debug" />
<label for="debug-no">{{ I18N[lang].no }}</label>
</td>
</tr>
<!-- Enable ZTS -->
<tr>
<td>{{ I18N[lang].useZTS }}</td>
<td>
<input type="radio" id="zts-yes" :value="1" v-model="zts" />
<label for="zts-yes">{{ I18N[lang].yes }}</label>
<input type="radio" id="zts-no" :value="0" v-model="zts" />
<label for="zts-no">{{ I18N[lang].no }}</label>
</td>
</tr>
<!-- download corresponding extensions -->
<tr>
<td>{{ I18N[lang].resultShowDownload }}</td>
<td>
<input type="radio" id="show-download-yes" :value="1" v-model="downloadByExt" />
<label for="show-download-yes">{{ I18N[lang].yes }}</label>
<input type="radio" id="show-download-no" :value="0" v-model="downloadByExt" />
<label for="show-download-no">{{ I18N[lang].no }}</label>
</td>
</tr>
<!-- Download pre-built -->
<tr>
<td>{{ I18N[lang].usePreBuilt }}</td>
<td>
<input type="radio" id="pre-built-yes" :value="1" v-model="preBuilt" />
<label for="pre-built-yes">{{ I18N[lang].yes }}</label>
<input type="radio" id="pre-built-no" :value="0" v-model="preBuilt" />
<label for="pre-built-no">{{ I18N[lang].no }}</label>
</td>
</tr>
<!-- Enable UPX -->
<tr v-if="selectedSystem !== 'macos'">
<td>{{ I18N[lang].useUPX }}</td>
<td>
<input type="radio" id="upx-yes" :value="1" v-model="enableUPX" />
<label for="upx-yes">{{ I18N[lang].yes }}</label>
<input type="radio" id="upx-no" :value="0" v-model="enableUPX" />
<label for="upx-no">{{ I18N[lang].no }}</label>
</td>
</tr>
</table>

<input type="radio" id="zts-no" :value="0" v-model="zts" />
<label for="zts-no">{{ I18N[lang].no }}</label>
</div>
<div class="option-line">
<span class="option-title">{{ I18N[lang].resultShowDownload }}</span>
<input type="radio" id="show-download-yes" :value="1" v-model="downloadByExt" />
<label for="show-download-yes">{{ I18N[lang].yes }}</label>

<input type="radio" id="show-download-no" :value="0" v-model="downloadByExt" />
<label for="show-download-no">{{ I18N[lang].no }}</label>
</div>
<div class="option-line" v-if="selectedSystem !== 'macos'">
<span class="option-title">{{ I18N[lang].useUPX }}</span>
<input type="radio" id="upx-yes" :value="1" v-model="enableUPX" />
<label for="upx-yes">{{ I18N[lang].yes }}</label>

<input type="radio" id="upx-no" :value="0" v-model="enableUPX" />
<label for="upx-no">{{ I18N[lang].no }}</label>
</div>
<h2>{{ I18N[lang].hardcodedINI }}</h2>
<textarea class="textarea" :placeholder="I18N[lang].hardcodedINIPlacehoder" v-model="hardcodedINIData" rows="5" />
<h2>{{ I18N[lang].resultShow }}</h2>
Expand All @@ -116,11 +140,11 @@
</div>
<div v-if="downloadByExt" class="command-container">
<b>{{ I18N[lang].downloadExtOnlyCommand }}</b>
<div class="command-preview">{{ spcCommand }} download --with-php={{ selectedPhpVersion }} --for-extensions "{{ extList }}"{{ debug ? ' --debug' : '' }}</div>
<div class="command-preview">{{ spcCommand }} download --with-php={{ selectedPhpVersion }} --for-extensions "{{ extList }}"{{ preBuilt ? ' --prefer-pre-built' : '' }}{{ debug ? ' --debug' : '' }}</div>
</div>
<div v-else class="command-container">
<b>{{ I18N[lang].downloadAllCommand }}</b>
<div class="command-preview">{{ spcCommand }} download --all --with-php={{ selectedPhpVersion }}{{ debug ? ' --debug' : '' }}</div>
<div class="command-preview">{{ spcCommand }} download --all --with-php={{ selectedPhpVersion }}{{ preBuilt ? ' --prefer-pre-built' : '' }}{{ debug ? ' --debug' : '' }}</div>
</div>
<div class="command-container" v-if="enableUPX">
<b>{{ I18N[lang].downloadUPXCommand }}</b>
Expand Down Expand Up @@ -162,6 +186,14 @@ const osList = [
{ os: 'windows', label: 'Windows', disabled: false },
];
const isSupported = (extName, os) => {
// Convert os to target: linux->Linux, macos->Darwin, windows->Windows (using map)
const a = new Map([['linux', 'Linux'], ['macos', 'Darwin'], ['windows', 'Windows']]);
const osName = a.get(os);
const osSupport = ext.value[extName]?.support?.[osName] ?? 'yes';
return osSupport === 'yes' || osSupport === 'partial';
};
const availablePhpVersions = [
'7.4',
'8.0',
Expand Down Expand Up @@ -201,8 +233,9 @@ const I18N = {
depTips: '选择扩展后，不可选中的项目为必需的依赖，编译的依赖库列表中可选的为现有扩展和依赖库的可选依赖。选择可选依赖后，将生成 --with-libs 参数。',
microUnavailable: 'micro 不支持 PHP 7.4 及更早版本！',
windowsSAPIUnavailable: 'Windows 目前不支持 fpm、embed 构建！',
useUPX: '是否开启 UPX 压缩（减小二进制体积，但很少见的情况下 micro SAPI 无法使用）',
useUPX: '是否开启 UPX 压缩（减小二进制体积）',
windowsDownSPCWarning: 'Windows 下请手动下载 spc.exe 二进制文件并解压到当前目录！',
usePreBuilt: '如果可能，下载预编译的依赖库（减少编译时间）',
},
en: {
selectExt: 'Select Extensions',
Expand Down Expand Up @@ -234,8 +267,9 @@ const I18N = {
depTips: 'After selecting the extensions, the unselectable items are essential dependencies. In the compiled dependencies list, optional dependencies consist of existing extensions and optional dependencies of libraries. Optional dependencies will be added in --with-libs parameter.',
microUnavailable: 'Micro does not support PHP 7.4 and earlier versions!',
windowsSAPIUnavailable: 'Windows does not support fpm and embed build!',
useUPX: 'Enable UPX compression (reduce binary size, but in rare cases micro SAPI doesn\'t work with UPX)',
useUPX: 'Enable UPX compression (reduce binary size)',
windowsDownSPCWarning: 'Please download the spc.exe binary file manually and extract it to the current directory on Windows!',
usePreBuilt: 'Download pre-built dependencies if possible (reduce compile time)',
}
};
Expand Down Expand Up @@ -305,6 +339,9 @@ const zts = ref(0);
// chosen download by extensions
const downloadByExt = ref(1);
// use pre-built
const preBuilt = ref(1);
// chosen upx
const enableUPX = ref(0);
Expand Down
Loading

0 comments on commit 758b697

Please sign in to comment.