From 17b69ec1e93e4e976b16f5e278503c6a467d262e Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Wed, 10 Jan 2024 11:11:45 +0800 Subject: [PATCH] update README --- README-zh.md | 161 +++++++++++++++++++++++++---------------------- README.md | 172 ++++++++++++++++++++++++++------------------------- 2 files changed, 173 insertions(+), 160 deletions(-) diff --git a/README-zh.md b/README-zh.md index 68602e84..9791335a 100755 --- a/README-zh.md +++ b/README-zh.md @@ -1,32 +1,44 @@ # static-php-cli -Build single static PHP binary, with PHP project together, with popular extensions included. - -🌐 **[中文](README-zh.md)** | **[English](README.md)** - -编译纯静态的 PHP Binary 二进制文件，带有各种扩展，让 PHP-cli 应用变得更便携！（cli SAPI） - -截屏2023-05-02 15 53 13 - -同时可以使用 micro 二进制文件，将 PHP 源码和 PHP 二进制构建为一个文件分发！（micro SAPI） - -截屏2023-05-02 15 52 33 - -> 该 SAPI 源自 [dixyes/phpmicro](https://github.com/dixyes/phpmicro) 的 [Fork 仓库](https://github.com/static-php/phpmicro)。 - -[![Version](https://img.shields.io/badge/Version-2.0.0-green.svg?style=flat-square)]() -[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)]() +[![Version](https://img.shields.io/packagist/v/crazywhalecc/static-php-cli?include_prereleases&label=Release&style=flat-square)]() [![](https://img.shields.io/github/actions/workflow/status/crazywhalecc/static-php-cli/tests.yml?branch=main&label=Build%20Test&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/actions/workflows/tests.yml) -[![](https://img.shields.io/badge/Extension%20Counter-75+-yellow.svg?style=flat-square)]() -[![](https://img.shields.io/github/search/crazywhalecc/static-php-cli/TODO?label=TODO%20Counter&style=flat-square)]() +[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)]() +[![](https://img.shields.io/badge/Extension%20Counter-75+-yellow.svg?style=flat-square)]([https://static-php.dev/](https://static-php.dev/en/guide/extensions.html)) +[![](https://dcbadge.vercel.app/api/server/RNpegEYW?style=flat-square&compact=true&theme=default-inverted)](https://discord.gg/RNpegEYW) -> 项目名称是 static-php-cli，但其实支持 cli、fpm、micro 和 embed SAPI 😎 +**static-php-cli**是一个用于静态编译、构建 PHP 解释器的工具，支持众多流行扩展。 + +目前 static-php-cli 支持 `cli`、`fpm`、`embed` 和 `micro` SAPI。 + +**static-php-cli**也支持将 PHP 代码和 PHP 运行时打包为一个文件并运行。 + +- [README - English](./README.md) +- [README - 中文](./README-zh.md) + +## 特性 + +static-php-cli（简称 `spc`）有许多特性： + +- :handbag: 构建独立的单文件 PHP 解释器，无需任何依赖 +- :hamburger: 构建 **[phpmicro](https://github.com/dixyes/phpmicro)** 自执行二进制（将 PHP 代码和 PHP 解释器打包为一个文件） +- :pill: 提供一键检查和修复编译环境的 Doctor 模块 +- :zap: 支持多个系统：`Linux`、`macOS`、`FreeBSD`、[`Windows (WIP)`](https://github.com/crazywhalecc/static-php-cli/pull/301) +- :wrench: 高度自定义的代码 patch 功能 +- :books: 自带编译依赖管理 +- 📦 提供由自身编译的独立 `spc` 二进制（使用 spc 和 [box](https://github.com/box-project/box) 构建） +- :fire: 支持大量 [扩展](https://static-php.dev/zh/guide/extensions.html) + +**静态 php-cli:** +out1 + +**使用 phpmicro 打包 PHP 代码:** +out2 ## 文档 目前 README 编写了基本用法。有关 static-php-cli 所有的功能，请点击这里查看文档：。 -## 自托管直接下载 +## 直接下载 如果你不想自行编译 PHP，可以从本项目现有的示例 Action 下载 Artifact，也可以从自托管的服务器下载。 @@ -38,6 +50,10 @@ Build single static PHP binary, with PHP project together, with popular extensio ### 编译环境需求 +- PHP >= 8.1（spc 自身是用 PHP 写的） +- 扩展：`mbstring,pcntl,posix,tokenizer,phar` +- 系统安装了 `curl` 和 `git` + 是的，本项目采用 PHP 编写，编译前需要一个 PHP 环境，比较滑稽。 但本项目默认可通过自身构建的 micro 和 static-php 二进制运行，其他只需要包含 mbstring、pcntl 扩展和 PHP 版本大于等于 8.1 即可。 @@ -50,11 +66,9 @@ Build single static PHP binary, with PHP project together, with popular extensio | Windows | | | | FreeBSD | :computer: | :computer: | -> macOS-arm64 因 GitHub 暂未提供 arm runner，如果要构建 arm 二进制，可以使用手动构建。 - 目前支持编译的 PHP 版本为：`7.3`，`7.4`，`8.0`，`8.1`，`8.2`，`8.3`。 -### 支持的扩展情况 +### 支持的扩展 请先根据下方扩展列表选择你要编译的扩展。 @@ -63,7 +77,7 @@ Build single static PHP binary, with PHP project together, with popular extensio > 如果这里没有你需要的扩展，可以提交 Issue。 -### 使用 Actions 构建 +### 在线构建（使用 GitHub Actions） 使用 GitHub Action 可以方便地构建一个静态编译的 PHP，同时可以自行定义要编译的扩展。 @@ -74,72 +88,77 @@ Build single static PHP binary, with PHP project together, with popular extensio 如果你选择了 `debug`，则会在构建时输出所有日志，包括编译的日志，以供排查错误。 -### 手动构建（使用 SPC 二进制） +### 本地构建（使用 spc 二进制） -本项目提供了一个 static-php-cli 的二进制文件，你可以直接下载对应平台的二进制文件，然后使用它来构建静态的 PHP。目前 `spc` 二进制支持的平台有 Linux 和 macOS。 +该项目提供了 static-php-cli 的二进制文件：`spc`。 +您可以使用 `spc` 二进制文件，无需安装任何运行时（用起来就像 golang 程序）。 +目前，`spc` 二进制文件提供的平台有 Linux 和 macOS。 -下面是从 GitHub Action 下载的方法： - -1. 进入 [GitHub Action](https://github.com/crazywhalecc/static-php-cli/actions/workflows/release-build.yml)。 -2. 选择一个最新的构建任务，进入后选择 `Artifacts`，下载对应平台的二进制文件。 -3. 解压 `.zip` 文件。解压后，为其添加执行权限：`chmod +x ./spc`。 - -你也可以从自托管的服务器下载二进制文件：[进入](https://dl.static-php.dev/static-php-cli/spc-bin/nightly/)。 - -### 手动构建（使用源码） - -先克隆本项目： +使用以下命令从自托管服务器下载： ```bash +# Download from self-hosted nightly builds (sync with main branch) +# For Linux x86_64 +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64 +# For Linux aarch64 +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64 +# macOS x86_64 (Intel) +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64 +# macOS aarch64 (Apple) +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64 + +# add x perm +chmod +x ./spc +./spc --version +``` + +自托管 `spc` 由 GitHub Actions 构建，你也可以从 Actions 直接下载：[此处](https://github.com/crazywhalecc/static-php-cli/actions/workflows/release-build.yml)。 + +### 本地构建（使用 git 源码） + +```bash +# clone 仓库即可 git clone https://github.com/crazywhalecc/static-php-cli.git ``` -如果你本机没有安装 PHP，你需要先使用包管理（例如 brew、apt、yum、apk 等）安装 php。 - -你也可以通过 `bin/setup-runtime` 命令下载静态编译好的 php-cli 和 Composer。下载的 php 和 Composer 将保存为 `bin/php` 和 `bin/composer`。 +如果您的系统上尚未安装 php，我们建议你使用内置的 setup-runtime 自动安装 PHP 和 Composer。 ```bash cd static-php-cli chmod +x bin/setup-runtime -./bin/setup-runtime - -# 使用独立的 php 运行 static-php-cli -./bin/php bin/spc - -# 使用 composer -./bin/php bin/composer - -# 初始化本项目 -cd static-php-cli -composer update +# it will download static php (from self-hosted server) and composer (from getcomposer) +bin/setup-runtime +# initialize composer deps +bin/composer install +# chmod chmod +x bin/spc +bin/spc --version ``` -### 使用 static-php-cli 命令行程序 +### 开始构建 PHP -下面是使用 static-php-cli 编译静态 php 和 micro 的基础用法： +下面是使用 static-php-cli 的基础用法： -> 如果你使用的是打包好的 `spc` 二进制，你需要将下列命令的 `bin/spc` 替换为 `./spc`。 +> 如果你使用的是打包好的 `spc` 二进制，你需要将下列命令的 `./bin/spc` 替换为 `./spc`。 ```bash -# 检查环境依赖，并根据提示的命令安装缺失的编译工具 -./bin/spc doctor +# 检查环境依赖，并根据尝试自动安装缺失的编译工具 +./bin/spc doctor --auto-fix + # 拉取所有依赖库 -./bin/spc fetch --all -# 只拉取编译指定扩展需要的所有依赖 +./bin/spc download --all +# 只拉取编译指定扩展需要的所有依赖（推荐） ./bin/spc download --for-extensions=openssl,pcntl,mbstring,pdo_sqlite +# 下载编译不同版本的 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 ``` -你也可以使用参数 `--with-php=x.y` 来指定下载的 PHP 版本，目前支持 7.3 ~ 8.3： - -```bash -# 优先考虑使用 >= 8.0 的 PHP 版本，因为 phpmicro 不支持在 PHP7 中构建 -./bin/spc download --with-php=8.2 --all -``` - -其中，目前支持构建 cli，micro，fpm 三种静态二进制，使用以下参数的一个或多个来指定编译的 SAPI： +其中，目前支持构建 cli，micro，fpm 和 embed，使用以下参数的一个或多个来指定编译的 SAPI： - `--build-cli`：构建 cli 二进制 - `--build-micro`：构建 phpmicro 自执行二进制 @@ -151,17 +170,9 @@ chmod +x bin/spc ```bash ./bin/spc build openssl,pcntl,mbstring --debug --build-all -./bin/spc fetch --all --debug +./bin/spc download --all --debug ``` -此外，默认编译的 PHP 为 NTS 版本。如需编译线程安全版本（ZTS），只需添加参数 `--enable-zts` 即可。 - -```bash -./bin/spc build openssl,pcntl --build-all --enable-zts -``` - -同时，你也可以使用参数 `--no-strip` 来关闭裁剪，关闭裁剪后可以使用 gdb 等工具调试，但这样会让静态二进制体积变大。 - ## 不同 SAPI 的使用 ### 使用 cli diff --git a/README.md b/README.md index aa7f1043..157e589f 100755 --- a/README.md +++ b/README.md @@ -1,28 +1,40 @@ # static-php-cli -Build single static PHP binary, with PHP project together, with popular extensions included. - -🌐 **[中文](README-zh.md)** | **[English](README.md)** - -> Windows support will be added in v2.1. - -The project name is static-php-cli, but it actually supports cli, fpm, micro and embed SAPI 😎 - -Compile a purely static php-cli binary file with various extensions to make PHP applications more portable! (cli SAPI) - -2023-05-02 15 53 13 - -You can also use the micro binary file to combine php binary and php source code into one for distribution! (micro SAPI) - -2023-05-02 15 52 33 - -> This SAPI feature is from the [Fork](https://github.com/static-php/phpmicro) of [dixyes/phpmicro](https://github.com/dixyes/phpmicro). - -[![Version](https://img.shields.io/badge/Version-2.0.0-green.svg?style=flat-square)]() -[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)]() +[![Version](https://img.shields.io/packagist/v/crazywhalecc/static-php-cli?include_prereleases&label=Release&style=flat-square)]() [![](https://img.shields.io/github/actions/workflow/status/crazywhalecc/static-php-cli/tests.yml?branch=main&label=Build%20Test&style=flat-square)](https://github.com/crazywhalecc/static-php-cli/actions/workflows/tests.yml) +[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)]() [![](https://img.shields.io/badge/Extension%20Counter-75+-yellow.svg?style=flat-square)]([https://static-php.dev/](https://static-php.dev/en/guide/extensions.html)) -[![](https://img.shields.io/github/search/crazywhalecc/static-php-cli/TODO?label=TODO%20Counter&style=flat-square)]() +[![](https://dcbadge.vercel.app/api/server/RNpegEYW?style=flat-square&compact=true&theme=default-inverted)](https://discord.gg/RNpegEYW) + +**static-php-cli** is a powerful tool designed for building static, standalone PHP runtime +with popular extensions. + +Static PHP built by **static-php-cli** supports `cli`, `fpm`, `embed` and `micro` SAPI. + +**static-php-cli** also has the ability to package PHP projects +along with the PHP interpreter into one single executable file. + +- [README - English](./README.md) +- [README - 中文](./README-zh.md) + +## Features + +static-php-cli (you can call it `spc`) has a lot of features: + +- :handbag: Build single-file php executable, without any dependencies +- :hamburger: Build **[phpmicro](https://github.com/dixyes/phpmicro)** self-extracted executable (glue php binary and php source code into one file) +- :pill: Automatic build environment checker (Doctor module) +- :zap: `Linux`, `macOS`, `FreeBSD`, [`Windows (WIP)`](https://github.com/crazywhalecc/static-php-cli/pull/301) support +- :wrench: Configurable source code patches +- :books: Build dependency management +- 📦 Provide `spc` own standalone executable (built by spc and [box](https://github.com/box-project/box)) +- :fire: Support many popular [extensions](https://static-php.dev/en/guide/extensions.html) + +**Single-file standalone php-cli:** +out1 + +**Combine PHP code with PHP interpreter using phpmicro:** +out2 ## Documentation @@ -31,7 +43,7 @@ see . ## Direct Download -If you don't want to compile yourself, you can download example pre-compiled artifact from [Actions](https://github.com/static-php/static-php-cli-hosted/actions/workflows/build-php-common.yml), or from self-hosted server. +If you don't want to build or want to test first, you can download example pre-compiled artifact from [Actions](https://github.com/static-php/static-php-cli-hosted/actions/workflows/build-php-bulk.yml), or from self-hosted server. Below are several precompiled static-php binaries with different extension combinations, which can be downloaded directly according to your needs. @@ -40,14 +52,18 @@ which can be downloaded directly according to your needs. - [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 70MB 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 6MB in size. -## Use static-php-cli to build PHP +## Build ### Compilation Requirements -Yes, this project is written in PHP, pretty funny. +- PHP >= 8.1 (static-php-cli is written in PHP) +- Extension: `mbstring,pcntl,posix,tokenizer,phar` +- Supported OS with `curl` and `git` installed + +You can say I made a PHP builder written in PHP, pretty funny. But static-php-cli runtime only requires an environment above PHP 8.1 and `mbstring`, `pcntl` extension. -Here is the architecture support status, where :octocat: represents support for GitHub Action builds, +Here is the supported OS and arch, where :octocat: represents support for GitHub Action builds, :computer: represents support for local manual builds, and blank represents not currently supported. | | x86_64 | aarch64 | @@ -57,8 +73,6 @@ Here is the architecture support status, where :octocat: represents support for | Windows | | | | FreeBSD | :computer: | :computer: | -> macOS-arm64 is not supported for GitHub Actions, if you are going to build on arm, you can build it manually on your own machine. - Currently supported PHP versions for compilation are: `7.3`, `7.4`, `8.0`, `8.1`, `8.2`, `8.3`. ### Supported Extensions @@ -72,7 +86,7 @@ Please first select the extension you want to compile based on the extension lis Here is the current planned roadmap for extension support: [#152](https://github.com/crazywhalecc/static-php-cli/issues/152) . -### GitHub Actions Build +### Build Online (using GitHub Actions) Use GitHub Action to easily build a statically compiled PHP, and at the same time define the extensions to be compiled by yourself. @@ -84,80 +98,77 @@ 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. -- When using ubuntu-latest, it will build linux-x86_64 binary. -- When using macos-latest, it will build macOS-x86_64 binary. +### Build Locally (using SPC binary) -### Manual build (using SPC binary) - -This project provides a binary file of static-php-cli. -You can directly download the binary file of the corresponding platform and then use it to build static PHP. +This project provides a binary file of static-php-cli: `spc`. +You can use `spc` binary instead of installing any runtime like golang app. Currently, the platforms supported by `spc` binary are Linux and macOS. -Here's how to download from GitHub Actions: - -1. Enter [GitHub Actions](https://github.com/crazywhalecc/static-php-cli/actions/workflows/release-build.yml) or [self-hosted nightly builds](https://dl.static-php.dev/static-php-cli/spc-bin/nightly/). -2. If you download from GHA, select the latest build task, select `Artifacts`, and download the binary file of the corresponding platform. -3. If you download from GHA, unzip the `.zip` file. After decompressing, add execution permissions to it: `chmod +x ./spc`. -4. If you download from self-hosted server, download `spc-$os-$arch` file and just use it (don't forget `chmod +x`). - -> SPC single-file binary is built by phpmicro and box, and it doesn't need to install PHP. Just treat `spc` as a standalone executable. - -### Manual build (using source code) - -Clone repo first: +Download from self-hosted nightly builds using commands below: ```bash +# Download from self-hosted nightly builds (sync with main branch) +# For Linux x86_64 +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64 +# For Linux aarch64 +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64 +# macOS x86_64 (Intel) +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64 +# macOS aarch64 (Apple) +curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64 + +# add x perm +chmod +x ./spc +./spc --version +``` + +Self-hosted `spc` is built by GitHub Actions, you can also download from Actions artifacts [here](https://github.com/crazywhalecc/static-php-cli/actions/workflows/release-build.yml). + +### Build Locally (using git source) + +```bash +# just clone me! git clone https://github.com/crazywhalecc/static-php-cli.git ``` -If you have not installed php on your system, you can use package management to install PHP (such as brew, apt, yum, apk etc.). - -And you can also download single-file php binary and composer using command `bin/setup-runtime`. -The PHP runtime for static-php-cli itself will be downloaded at `bin/php`, and composer is at `bin/composer`. +If you have not installed php on your system, we recommend that you use the built-in setup-runtime to install PHP and Composer automatically. ```bash cd static-php-cli chmod +x bin/setup-runtime -# It will download php-cli from self-hosted server and composer from getcomposer.org -./bin/setup-runtime - -# Use this php runtime to run static-php-cli compiler -./bin/php bin/spc - -# Use composer -./bin/php bin/composer - -# Initialize this project -cd static-php-cli -composer update +# it will download static php (from self-hosted server) and composer (from getcomposer) +bin/setup-runtime +# initialize composer deps +bin/composer install +# chmod chmod +x bin/spc +bin/spc --version ``` -### Use static-php-cli +### Start Building PHP -Basic usage for building php and micro with some extensions: +Basic usage for building php with some extensions: > If you are using the packaged `spc` binary, you need to replace `bin/spc` with `./spc` in the following commands. ```bash -# Check system tool dependencies, fix them if possible -./bin/spc doctor +# Check system tool dependencies, auto-fix them if possible +./bin/spc doctor --auto-fix + # fetch all libraries ./bin/spc download --all -# only fetch necessary sources by needed extensions +# only fetch necessary sources by needed extensions (recommended) ./bin/spc download --for-extensions=openssl,pcntl,mbstring,pdo_sqlite +# 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 ``` -You can also use the parameter `--with-php=x.y` to specify the downloaded PHP version, currently supports 7.4 ~ 8.3: - -```bash -# Using PHP >= 8.0 is recommended, because PHP7 cannot use phpmicro -./bin/spc fetch --with-php=8.2 --all -``` - -Now we support `cli`, `micro`, `fpm`, you can use one or more of the following parameters to specify the compiled SAPI: +Now we support `cli`, `micro`, `fpm` and `embed` SAPI. You can use one or more of the following parameters to specify the compiled SAPI: - `--build-cli`: build static cli executable - `--build-micro`: build static phpmicro self-extracted executable @@ -169,17 +180,9 @@ If anything goes wrong, use `--debug` option to display full terminal output: ```bash ./bin/spc build openssl,pcntl,mbstring --debug --build-all -./bin/spc fetch --all --debug +./bin/spc download --all --debug ``` -In addition, we build NTS (non-thread-safe) by default. If you are going to build ZTS version, just add `--enable-zts` option. - -```bash -./bin/spc build openssl,pcntl --build-all --enable-zts -``` - -Adding option `--no-strip` can produce binaries with debug symbols, in order to debug (using gdb). Disabling strip will increase the size of static binary. - ## Different SAPI Usage ### Use cli @@ -288,4 +291,3 @@ and they all have their own open source licenses. Please use the `bin/spc dump-license` command to export the open source licenses used in the project after compilation, and comply with the corresponding project's LICENSE. -