From 21c582d309717685eb46c016fc8b63b7c5dfba7b Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Sat, 18 Mar 2023 14:19:45 +0800 Subject: [PATCH] update README --- README-en.md | 255 ++++++++++++++++++----------------------------- README.md | 276 ++++++++++++++++----------------------------------- 2 files changed, 185 insertions(+), 346 deletions(-) diff --git a/README-en.md b/README-en.md index 3cc6cd76..34875ed6 100755 --- a/README-en.md +++ b/README-en.md @@ -1,180 +1,121 @@ # static-php-cli +Compile A Statically Linked PHP With Swoole and other Extensions. -Compile A Statically Linked PHP With Swoole and other Popular Extensions. +Compile a purely static PHP binary file with various extensions to make PHP-cli applications more portable! -Compile A Single Binary With PHP Code. +You can also use the micro binary file to package PHP source code and binary files into one for distribution! -**If you are intrested in this project, don't miss this discussion: ** - -[![version](https://img.shields.io/badge/version-1.5.2-green.svg)]() -![Build Actions](https://github.com/crazywhalecc/static-php-cli/actions/workflows/build-php.yml/badge.svg) +Note: only support cli SAPI, not support fpm, cgi. ## Compilation Requirements -- Supporting architecture: `x86_64`, `arm64(aarch64)`, `armv7(armv7l)` -- Docker required (or alpine linux 3.13+) -- PHP version from 7.2 to 8.1 -- Micro Package requires PHP >= 8.0 +Yes, this project is written in PHP, pretty funny. +But php-static-cli only requires an environment above PHP 8.0. -## Runtime Requirements +- Linux + - Supported arch: aarch64, amd64 + - Supported distributions: alpine, ubuntu, centos + - Requirements: (TODO) +- macOS + - Supported arch: arm64, x86_64 + - Requirements: make, bison, flex, pkg-config, git, autoconf, automake, tar, unzip, xz, gzip, bzip2, cmake +- Windows + - Supported arch: x86_64 + - Requirements: (TODO) +- PHP + - Supported version: 8.0, 8.1, 8.2 -Linux +## Usage (WIP) -## Usage +After stable release for this project, a single phar and single binary for this tool will be published. -1. Directly download static binary from this link or [Actions uploaded artifacts](https://github.com/crazywhalecc/static-php-cli/actions). - - - -2. Use fast install script `install-runtime.sh` to download static php and composer distribution into `runtime/` directory - -But this script has some Chinese comments and prompts, if you cannot understand or have to use it in English, I will make an pure international version! :) +And currently you may need to clone this branch and edit GitHub Action to build. ```bash -bash -c "`curl -fsSL https://raw.githubusercontent.com/crazywhalecc/static-php-cli/master/install-runtime.sh`" +chmod +x static-php-cli +# 拉取所有依赖库 +./static-php-cli fetch --all +# 构建包含 bcmath 扩展的 php-cli 和 micro.sfx +./static-php-cli build "bcmath" "" --build-all ``` -## Packing PHP Code into a Static Binary +## Current Status -From v1.5.0, we support packing PHP code into a static binary. You can pack your PHP code into a static binary by micro. +- [X] Basic CLI framework (by symfony/console) +- [ ] Linux support +- [ ] macOS support +- [X] Exception handler +- [ ] Windows support +- [ ] PHP 7.4 support -You can directly download `micro-` prefix file, untar it and you will get file `micro.sfx`. +## Supported Extensions -Here's a simple example to use it: +> - yes: supported and tested +> - untested: supported but not tested +> - empty: not supported yet -```bash -echo " code.php -cat micro.sfx code.php > single-app && chmod +x single-app -./single-app +| | Linux | macOS | Windows | +|------------|-------|----------|---------| +| bcmath | | yes | | +| calendar | | | |` +| ctype | | | | +| curl | | | | +| date | | yes | | +| dom | | | | +| event | | | | +| exif | | | | +| filter | | | | +| fileinfo | | | | +| ftp | | | | +| gd | | untested | | +| hash | | yes | | +| iconv | | | | +| inotify | | | | +| json | | yes | | +| libxml | | | | +| mbstring | | | | +| mongodb | | | | +| mysqli | | | | +| mysqlnd | | | | +| openssl | | yes | | +| pcntl | | untested | | +| pcre | | yes | | +| pdo | | yes | | +| pdo_mysql | | | | +| pdo_sqlite | | yes | | +| pdo_pgsql | | | | +| phar | | | | +| posix | | | | +| protobuf | | | | +| readline | | | | +| redis | | | | +| Reflection | | yes | | +| shmop | | | | +| simplexml | | | | +| soap | | | | +| sockets | | | | +| sqlite3 | | untested | | +| swow | | | | +| swoole | | yes | | +| tokenizer | | | | +| xml | | | | +| xmlreader | | | | +| xmlwriter | | | | +| zip | | | | +| zlib | | | | -# If packing phar into a static binary, just change code.php to your phar path. -``` -> Note: It means that your PHP code won't be compiled and you can't protect your source code by using micro! -> -> If you are looking for compiling PHP code or encrypting code, here's not your solution. -> -> Special thanks: +## Open-Source LICENSE -## Compiling +This project is based on the tradition of using the MIT License for old versions, +while the new version references source code from some other projects. +Special thanks to: -Here's help command to compile it yourself: +- dixyes/lwmbs (Mulun Permissive License) +- swoole/swoole-cli (Apache 2.0 LICENSE+SWOOLE-CLI LICENSE) +- +Due to the special nature of this project, +many other open source projects such as curl and protobuf will be used during the project compilation process, +and they all have their own open source licenses. -```bash -git clone https://github.com/crazywhalecc/static-php-cli.git -cd static-php-cli/docker -docker build -t static-php . --build-arg USE_BACKUP_ADDRESS=yes -# Making a directory to put binary files -mkdir dist -# It will ask you for PHP version, extensions, and compile static binaries -docker run --rm -v $(pwd)/dist:/dist/ -it static-php build-php -``` - -After compilation you can use command to get static php binary file. - -```bash -cd dist -file ./php -``` - -If you don't want to use docker, a single script for compiling in **Alpine Linux**: - -```bash -cd docker -# Change PHP Version -export VER_PHP="8.1.7" -# Use Original download link (Default is China mainland mirror link, for others please use 'yes' for original link) -export USE_BACKUP="yes" -./fast-compiler.sh -``` - -To customize PHP extensions, edit `docker/extensions.txt` file, and rules below: -- Use `^` as deselect, to mark not install. Use `#` as comments. -- extensions name uses lower case, and default file contains all supported extensions, if u need other extensions, consider write an Issue - -## Supported PHP extensions -| Support | PHP Ext Name | Version | Comments | -| ------- | ------------ | ------- | ---------------------------------------- | -| yes | bcmath | * | | -| yes | calendar | * | | -| yes | ctype | * | | -| yes | curl | * | | -| yes | dom | * | | -| yes | event | >=3.0.8 | author's bitbucket version, not pecl | -| yes | exif | * | | -| yes | filter | * | | -| yes | fileinfo | * | | -| yes | gd | * | | -| yes | hash | * | | -| yes | iconv | * | | -| yes | inotify | 3.0.0 | | -| yes | json | * | | -| yes | libxml | * | | -| yes | mbstring | * | | -| yes | mongodb | >=1.9.1 | not tested | -| | mysqli | | | -| yes | mysqlnd | * | | -| yes | openssl | * | | -| yes | pcntl | * | | -| yes | pdo | * | | -| yes | pdo_mysql | * | | -| yes | pdo_sqlite | * | | -| | pdo_pgsql | * | | -| yes | phar | * | | -| yes | posix | * | | -| yes, not compiled | protobuf | * | Not compiled and enabled as default | -| yes | readline | * | Not support `./php -a` | -| yes | redis | * | | -| yes | shmop | * | | -| yes | simplexml | * | | -| yes | soap | * | | -| yes | sockets | * | | -| yes | sqlite3 | * | | -| yes | swoole | >=4.6.6 | support mysqlnd, sockets, openssl, redis | -| yes | tokenizer | * | | -| yes | xml | * | | -| yes | xmlreader | * | | -| yes | xmlwriter | * | | -| yes | zip | * | not support `bzip2`, `lzma` compression | -| yes | zlib | * | | - -## Customization -- If you are going to run without prompt, Just add it to the end of `docker run xxx` cmd according to the parameters given below. - -> 1st parameter `original` represents that you are using global original download address to fetch dependencies, if you are in mainland China, use `mirror`. -> -> 2nd parameter `8.1.7` is your PHP version you are compiling. -> -> 3rd parameter `all` represents that you will compile all supported extensions. -> -> 4th parameter `/dist/` is your binary output directory. -> -> For example, `docker run --rm -v $(pwd)/dist:/dist/ -it static-php build-php original 8.1.7 all /dist/` - -- `docker/extensions.txt` edit extensions. -- `docker/compile-php.sh` file `php_compile_args` function to adjust PHP configure arguments. -- `docker/check-extensions.sh` file `check_in_configure` function to adjust extensions' configure arguments. -- `docker/config.json` edit extensions and dependencies version and download links. - -## Current Issue -- [X] Not support event(libevent), because of its `config.m4` and code. -- [ ] Swoole not support `--enable-swoole-curl`. -- [X] Not support readline, maybe caused by ncurses library. -- [X] Not support curl (solved) -- [X] Customize extensions to compile -- [X] php.ini integration -- [X] i18n (including README and scripts) - -## Running preview - -### Using static binary - -未命名 - -### Using swoole application packed with micro - -all - -## References -- -- -- +Please use the `dump-license` command to export the open source licenses used in the project after compilation, +and comply with the corresponding project's LICENSE. diff --git a/README.md b/README.md index e3c67e67..755cfc98 100755 --- a/README.md +++ b/README.md @@ -1,217 +1,115 @@ # static-php-cli Compile A Statically Linked PHP With Swoole and other Extensions. [English README](README-en.md) -**如果你对本项目有兴趣，请看讨论进行投票：** - 编译纯静态的 PHP Binary 二进制文件，带有各种扩展，让 PHP-cli 应用变得更便携！ 同时可以使用 micro 二进制文件，将 PHP 源码和 PHP 二进制构建为一个文件分发！ -注：只能编译 CLI 模式，暂不支持 CGI 和 FPM 模式 +注：只能编译 CLI 模式，暂不支持 CGI 和 FPM 模式。 -[![版本](https://img.shields.io/badge/script--version-1.5.2-green.svg)]() [![License](https://img.shields.io/badge/License-MIT-blue.svg)]() -![Build Actions](https://github.com/crazywhalecc/static-php-cli/actions/workflows/build-php.yml/badge.svg) ## 编译环境需求 -- 目前支持 arm64、x86_64、armv7l 架构 -- 需要 Docker（也可以直接在 Alpine Linux 上使用） -- 脚本支持编译的 PHP 版本（7.2 ~ 8.1） +是的，本项目采用 PHP 编写，编译前需要一个 PHP 环境，比较滑稽。 +但本项目默认可通过自身构建的 micro 和 static-php 二进制运行，其他只需要包含 tokenizer 扩展和 PHP 版本大于等于 8.0 即可。 -## 运行环境需求 +- Linux + - 支持架构: aarch64, amd64 + - 支持发行版: alpine, ubuntu, centos + - 依赖工具: (TODO) +- macOS + - 支持架构: arm64, x86_64 + - 依赖工具: make, bison, flex, pkg-config, git, autoconf, automake, tar, unzip, xz, gzip, bzip2, cmake +- Windows + - 支持架构: x86_64 + - 依赖工具: (TODO) +- PHP + - 支持版本: 8.0, 8.1, 8.2 -Linux +## 使用（WIP） -## 直接使用 +> 你正在看的是重构后的 static-php-cli 编译项目，新项目还未完全重构，所以还有大量的扩展没有完成。 +> 你可以阅读使用 bash 编写的仅为 Linux 系统使用的静态编译脚本和 Docker，详见 bash-version 分支。 旧版本未来将会切换为次要版本，提供有限支持。 -1. 可以直接下面的托管服务器或到 `Actions` 找到最新的构建项目下载 Actions 构建的文件。 - - - -2. 可以直接使用快速脚本 `install-runtime.sh`，将静态 PHP 二进制及 Composer 下载到当前目录的 `runtime/` 子目录下： +未来会提供一个直接可使用的 phar 包和一个 phpmicro 打包的二进制文件，你可以直接从 Release 中获取并使用： ```bash -# 可以使用 export ZM_DOWN_PHP_VERION=8.0 来切换 PHP 版本 -bash <(curl -fsSL https://dl.zhamao.xin/php-bin/install-runtime.sh) +chmod +x static-php-cli +# 拉取所有依赖库 +./static-php-cli fetch --all +# 构建包含 bcmath 扩展的 php-cli 和 micro.sfx +./static-php-cli build "bcmath" "" --build-all ``` -## PHP 代码打包使用 +## 项目支持情况（WIP） -v1.5.0 脚本开始，脚本新增了对 PHP 代码打包的支持，可以将 PHP 代码打包为一个文件分发，方便在 Linux 系统使用。（仅支持 PHP >= 8.0） +- [X] 基础结构编写（采用 symfony/console`） +- [X] 错误处理 +- [ ] Windows 支持 +- [ ] Linux 支持 +- [ ] PHP 7.4 支持 -1. 可以直接在上面的下载链接中下载 `micro-` 开头的文件并解压，获得 `micro.sfx` 文件后，使用以下命令和 PHP 源码或 PHAR 结合： +## 支持的扩展情况（WIP） -```bash -echo " code.php -cat micro.sfx code.php > single-app && chmod +x single-app -./single-app +> Yes 代表已支持，Pending 代表支持但未经测试，空白代表暂不支持. -# 如果打包 PHAR 文件，仅需把 code.php 更换为 phar 文件路径即可 -``` +| | Linux | macOS | Windows | +|------------|-------|----------|---------| +| bcmath | | yes | | +| calendar | | | | +| ctype | | | | +| curl | | | | +| date | | yes | | +| dom | | | | +| event | | | | +| exif | | | | +| filter | | | | +| fileinfo | | | | +| ftp | | | | +| gd | | untested | | +| hash | | yes | | +| iconv | | | | +| inotify | | | | +| json | | yes | | +| libxml | | | | +| mbstring | | | | +| mongodb | | | | +| mysqli | | | | +| mysqlnd | | | | +| openssl | | yes | | +| pcntl | | untested | | +| pcre | | yes | | +| pdo | | yes | | +| pdo_mysql | | | | +| pdo_sqlite | | yes | | +| pdo_pgsql | | | | +| phar | | | | +| posix | | | | +| protobuf | | | | +| readline | | | | +| redis | | | | +| Reflection | | yes | | +| shmop | | | | +| simplexml | | | | +| soap | | | | +| sockets | | | | +| sqlite3 | | untested | | +| swow | | | | +| swoole | | yes | | +| tokenizer | | | | +| xml | | | | +| xmlreader | | | | +| xmlwriter | | | | +| zip | | | | +| zlib | | | | -2. 如果打包项目，可以先将项目打包为 phar + entry，然后结合打包 micro 与 phar 文件即可。 +## 开源协议 -> 关于如何将项目打包为 phar，见项目 [php-cli-helper](https://github.com/crazywhalecc/php-cli-helper)。 +本项目依据旧版本惯例采用 MIT License 开源，新版本采用了部分项目的源代码做参考，特别感谢： -> 感谢 项目提供的支持 +- dixyes/lwmbs（木兰宽松许可证） +- swoole/swoole-cli（Apache 2.0 LICENSE+SWOOLE-CLI LICENSE） -## 自行编译 - -可以自己使用 Dockerfile 进行编译构建： - -```bash - -git clone https://github.com/crazywhalecc/static-php-cli.git -cd static-php-cli/docker -export DOCKER_BUILDKIT=1 -docker build -t static-php . --build-arg USE_BACKUP_ADDRESS=no -# 新建一个用于放置构建好的二进制的文件夹 -mkdir dist -# 终端会引导你进行编译安装，可选择 PHP 版本、要编译的扩展 -docker run --rm -v $(pwd)/dist:/dist/ -it static-php build-php -``` - -编译之后可以使用下方命令将二进制 PHP 提取出来，用以下方式： - -```bash -cd dist -file ./php -# 如果是 PHP 8.0 以上，同时会输出 micro 构建版本 -file ./micro.sfx -``` - -如果你不想使用 Docker，想从Alpine环境直接编译，可以使用预置相同编译配置的脚本 `fast-compiler.sh`： - -```bash -cd docker -# 用于切换编译的PHP版本 -export VER_PHP="8.1.7" -./fast-compiler.sh -``` - -如果要选择安装的扩展，可以修改 `docker/extensions.txt` 文件，具体规则如下： -- 文件内使用 `^` 可以表示默认不安装该扩展，`#` 开头可以编写注释 -- 扩展名一律使用小写，目前默认状态下文件内所列的扩展为支持的扩展，其他扩展暂不支持，如有需求请提 Issue 添加 - -## 支持的扩展表 -| 是否支持 | PHP 扩展名称 | 支持版本 | 备注 | -| -------- | ------------ | -------- | ------------------------------------------------------- | -| yes, enabled | bcmath | * | | -| yes, enabled | calendar | * | | -| yes, enabled | ctype | * | | -| yes, enabled | curl | * | 自带下载编译 curl 库 | -| yes, enabled | dom | * | | -| yes, enabled | event | >=3.0.8 | 从 BitBucket 作者仓库下载，非 pecl 版本 | -| yes, enabled | exif | * | | -| yes, enabled | filter | * | | -| yes, enabled | fileinfo | * | | -| yes, enabled | gd | * | | -| yes, enabled | hash | * | | -| yes, enabled | iconv | * | | -| yes, enabled | inotify | 3.0.0 | 从 pecl 或镜像站下载的源码 | -| yes, enabled | json | * | | -| yes, enabled | libxml | * | 自带下载编译 libxml2 库 | -| yes, enabled | mbstring | * | | -| yes, enabled | mongodb | >=1.9.1 | 未测试，从 pecl 或镜像站下载的源码 | -| | mysqli | | | -| yes, enabled | mysqlnd | * | | -| yes, enabled | openssl | * | | -| yes, enabled | pcntl | * | | -| yes, enabled | pdo | * | | -| yes, enabled | pdo_mysql | * | | -| yes, enabled | pdo_sqlite | * | | -| | pdo_pgsql | * | | -| yes, enabled | phar | * | | -| yes, enabled | posix | * | | -| yes, not enabled | protobuf | * | 默认不编译 | -| yes, enabled | readline | * | 不支持 `./php -a` | -| yes, enabled | redis | * | 从 pecl 或镜像站下载的源码 | -| yes, enabled | shmop | * | | -| yes, enabled | simplexml | * | | -| yes, enabled | soap | * | | -| yes, enabled | sockets | * | | -| yes, enabled | sqlite3 | * | | -| yes, enabled | swoole | >=4.6.6 | 使用参数 `--enable-openssl --with-openssl --with-openssl-dir=/usr`，从 pecl 或镜像站下载的源码 | -| yes, enabled | tokenizer | * | | -| yes, enabled | xml | * | | -| yes, enabled | xmlreader | * | | -| yes, enabled | xmlwriter | * | | -| yes, enabled | zip | * | 因链接库原因已关闭 `libzip` 库的 `bzip2` 和 `lzma` 支持 | -| yes, enabled | zlib | * | | - -## 自定义 -- 从 Docker 运行编译，会依次询问下载地址、PHP 版本、要编译的扩展、编译输出文件夹。 -- 如果不想弹出终端交互框，只需按照下方给出的参数加到字符串的后面。 - -> `参数1`: `original` 代表使用原始地址，如果你位于中国大陆，可使用 `mirror` 加快下载。 -> -> `参数2`: `8.1.7` 是你要编译的 PHP 版本。 -> -> `参数3`: `all` 代表你要编译所有非反选的扩展，不询问。 -> -> `参数4`: `/dist/` 是你编译后输出二进制 PHP 和 micro 的文件夹 -> -> 基本例子: `docker run --rm -v $(pwd)/dist:/dist/ -it static-php build-php original 8.1.7 all /dist/` - -- `docker/extensions.txt` 指定要编译安装的扩展。 -- `docker/extensions.txt` 中，`^` 开头的扩展名为反选，反选的扩展将出现在编译的扩展列表中，但默认不选中。 -- `docker/compile-php.sh` 中的 `php_compile_args` 函数来调整 PHP 编译参数。 -- `docker/check-extensions.sh` 中的 `check_in_configure` 函数可调整 PHP 扩展编译的参数。 -- `docker/config.json` 可调整要下载的扩展和依赖库版本和链接。 -- `docker/fast-compiler.sh` 可以在 Alpine Linux 系统下直接运行。 - -## 目前的问题（对勾为已解决） -- [X] 不支持 event(libevent) 扩展，event 扩展的 sockets 支持不能在静态编译中使用，因为静态内嵌编译暂时没办法调整扩展编译顺序，同时其本身也不支持静态编译。 -- [ ] Swoole 扩展不支持 `--enable-swoole-curl`，也是因为编译顺序和加载顺序的问题。 -- [X] 不支持 readline 扩展，readline 扩展安装后无法正常使用 `php -a`，原因还没有弄清楚，可能是静态编译造成的 ncurses 库出现了问题。 -- [X] curl/libcurl 扩展静态编译 -- [X] 可自行选择不需要编译进入的扩展 -- [X] php.ini 内嵌或分发 -- [X] i18n（国际化脚本本身和 README） - -如果你对以上问题有解决方案，请提出 Issue 或 PR！ - -如果你对此脚本比较感兴趣，未来会在此编写脚本中涉及内容的解析和说明。 - -## 运行示例 - -### 静态 PHP 运行脚本 - -未命名 - -### micro 打包运行 Swoole - -all - -## 原理 - -静态编译是一项比较多见于 Golang 的编译方式，在传统的 Linux 系统下，正常的程序和库基本是动态编译链接（Dynamically linked）的，也就是说，不同程序引用同样的库可以共用，减少资源重复。 - -但是由于不少系统软件环境配置复杂，或者依赖的库版本冲突，一般使用 Docker 等容器技术可以解决这一问题。但 Docker 等容器也需要拉取镜像，体积较大，对于程序有便携需求的人（比如网络安全员做渗透测试等）需要很多程序可以像 Windows 上的绿色程序一样随处打包运行。 - -PHP 是最好的编程语言，它编写容易，易于部署和开发，倘若将 PHP 编译为静态的文件，并且将 Swoole 或 libevent 等库同样内嵌，那 PHP 不仅将可以编写便携的 Web 服务器，还能做很多想不到的事！ - -编译静态 PHP 大致分为以下几个步骤： -1. 下载 PHP 源码 -2. 下载需要静态编译的额外扩展源码（如 inotify、mongodb、redis 等） -3. 将额外扩展源码放入 PHP 源码中 -4. 生成 `configure` 并使用 `-static` 的 FLAG 进行生成 makefile -5. 修改 Makefile 中的编译参数，增加 `-all-static` 和去掉 dynamic 相关的参数 -6. 使用 `make` 构建静态 PHP -7. 使用 `make install` 安装到指定目录，再使用 `strip` 去除符号表缩小体积 - -对于第二步，如果额外扩展中有依赖 Linux 的其他库（比如 curl 依赖 libcurl），则需要在第二步之前编译安装对应库的静态版本（比如 libxml2.a） - -而此处出问题最多的部分就是安装额外扩展的依赖上，很多库不支持静态编译，而互联网很难找到对对应库进行静态编译的资料。 - -脚本和 Dockerfile 统一采用 Alpine 的目的就是，apk 包管理下有很多库提供了 `*-static` 静态版本，直接使用包管理安装就可以使用，而即使没有，也可以使用 musl-libc 进行静态编译，避免 glibc 下的 `libnss` 等无法静态编译的问题。 - -第二种要面对比较棘手的问题就是 PHP 扩展可能本身不支持静态编译（如 curl 扩展），有些通过绕过手段可以静态编译，但有些只能通过对扩展源码进行修改才能使其支持。 - -所以这个项目中涉及的脚本，最大的问题就在于对其他依赖的处理，而不是 PHP 编译本身。PHP 如果不启用任何扩展（即使用 `--disable-all`），则可以很方便地静态编译。 - -## 参考资料 -- -- -- +因本项目的特殊性，使用项目编译过程中会使用很多其他开源项目，例如 curl、protobuf 等，它们都有各自的开源协议。 +请在编译完成后，使用命令 `dump-license` 导出项目使用项目的开源协议，并遵守对应项目的 LICENSE。