2021-09-24 16:52:20 +00:00
|
|
|
# Contributing
|
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
## Compiling PHP
|
2022-10-04 12:36:03 +00:00
|
|
|
### With Docker (Linux)
|
|
|
|
|
2022-10-15 16:42:24 +00:00
|
|
|
Build the dev Docker image:
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2023-07-07 16:17:06 +00:00
|
|
|
docker build -t frankenphp-dev -f dev.Dockerfile .
|
2022-10-31 20:57:43 +00:00
|
|
|
docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 8080:8080 -p 443:443 -v $PWD:/go/src/app -it frankenphp-dev
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-15 16:42:24 +00:00
|
|
|
The image contains the usual development tools (Go, GDB, Valgrind, Neovim...).
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
### Without Docker (Linux and macOS)
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
[Follow the instructions to compile from sources](docs/compile.md) and pass the `--debug` configuration flag.
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
## Running the test suite
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
go test -race -v ./...
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
## Caddy module
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
Build Caddy with the FrankenPHP Caddy module:
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
cd caddy/frankenphp/
|
2022-10-04 12:36:03 +00:00
|
|
|
go build
|
2022-10-19 09:19:49 +00:00
|
|
|
cd ../../
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
Run the Caddy with the FrankenPHP Caddy module:
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
cd testdata/
|
|
|
|
../caddy/frankenphp/frankenphp run
|
2022-10-04 12:36:03 +00:00
|
|
|
|
|
|
|
The server is listening on `127.0.0.1:8080`:
|
|
|
|
|
2022-11-08 11:00:11 +00:00
|
|
|
curl -vk https://localhost/phpinfo.php
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
## Minimal test server
|
2022-10-04 12:36:03 +00:00
|
|
|
|
|
|
|
Build the minimal test server:
|
|
|
|
|
|
|
|
cd internal/testserver/
|
|
|
|
go build
|
2022-10-19 09:19:49 +00:00
|
|
|
cd ../../
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
Run the test server:
|
2022-10-04 12:36:03 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
cd testdata/
|
2022-10-04 12:36:03 +00:00
|
|
|
../internal/testserver/testserver
|
2022-10-13 16:05:22 +00:00
|
|
|
|
2022-10-19 09:19:49 +00:00
|
|
|
The server is listening on `127.0.0.1:8080`:
|
|
|
|
|
|
|
|
curl -v http://127.0.0.1:8080/phpinfo.php
|
|
|
|
|
2022-11-03 08:04:29 +00:00
|
|
|
# Building Docker Images Locally
|
|
|
|
|
|
|
|
Print bake plan:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker buildx bake -f docker-bake.hcl --print
|
|
|
|
```
|
|
|
|
|
|
|
|
Build FrankenPHP images for amd64 locally:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/amd64"
|
|
|
|
```
|
|
|
|
|
|
|
|
Build FrankenPHP images for arm64 locally:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/arm64"
|
|
|
|
```
|
|
|
|
|
|
|
|
Build FrankenPHP images from scratch for arm64 & amd64 and push to Docker Hub:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker buildx bake -f docker-bake.hcl --pull --no-cache --push
|
|
|
|
```
|
|
|
|
|
2023-07-10 10:00:15 +00:00
|
|
|
## Debugging Segmentation Faults in GitHub Actions
|
|
|
|
|
|
|
|
1. Open `.github/workflows/tests.yml`
|
|
|
|
2. Enable PHP debug symbols
|
|
|
|
```patch
|
|
|
|
- uses: shivammathur/setup-php@v2
|
|
|
|
# ...
|
|
|
|
env:
|
|
|
|
phpts: ts
|
|
|
|
+ debug: true
|
|
|
|
```
|
|
|
|
3. Enable `tmate` to connect to the container
|
|
|
|
```patch
|
|
|
|
- name: Set include flags
|
|
|
|
run: echo "CGO_CFLAGS=$(php-config --includes)" >> "$GITHUB_ENV"
|
|
|
|
+ - run: |
|
|
|
|
sudo apt install gdb
|
|
|
|
+ mkdir -p /home/runner/.config/gdb/
|
|
|
|
+ printf "set auto-load safe-path /\nhandle SIG34 nostop noprint pass" > /home/runner/.config/gdb/gdbinit
|
|
|
|
+ - uses: mxschmitt/action-tmate@v3
|
|
|
|
+ env:
|
|
|
|
+ GOFLAGS: "-w -gcflags=all=-N -gcflags=all=-l"
|
|
|
|
```
|
|
|
|
4. Open `frankenphp.go`
|
|
|
|
5. Enable `cgosymbolizer`
|
|
|
|
```patch
|
|
|
|
- //_ "github.com/ianlancetaylor/cgosymbolizer"
|
|
|
|
+ _ "github.com/ianlancetaylor/cgosymbolizer"
|
|
|
|
```
|
|
|
|
6. Download the module: `go get`
|
|
|
|
7. In the container, you can use GDB and the like:
|
|
|
|
```sh
|
|
|
|
sudo apt install gdb
|
|
|
|
mkdir -p /home/runner/.config/gdb/
|
|
|
|
go test -c -ldflags=-w
|
|
|
|
gdb --args ./frankenphp.test -test.run ^MyTest$
|
|
|
|
```
|
|
|
|
8. When the bug is fixed, revert all these changes
|
|
|
|
|
2022-10-13 16:05:22 +00:00
|
|
|
## Misc Dev Resources
|
|
|
|
|
|
|
|
* [PHP embedding in uWSGI](https://github.com/unbit/uwsgi/blob/master/plugins/php/php_plugin.c)
|
|
|
|
* [PHP embedding in NGINX Unit](https://github.com/nginx/unit/blob/master/src/nxt_php_sapi.c)
|
|
|
|
* [PHP embedding in Go (go-php)](https://github.com/deuill/go-php)
|
|
|
|
* [PHP embedding in Go (GoEmPHP)](https://github.com/mikespook/goemphp)
|
|
|
|
* [PHP embedding in C++](https://gist.github.com/paresy/3cbd4c6a469511ac7479aa0e7c42fea7)
|
|
|
|
* [Extending and Embedding PHP by Sara Golemon](https://books.google.fr/books?id=zMbGvK17_tYC&pg=PA254&lpg=PA254#v=onepage&q&f=false)
|
|
|
|
* [What the heck is TSRMLS_CC, anyway?](http://blog.golemon.com/2006/06/what-heck-is-tsrmlscc-anyway.html)
|
|
|
|
* [PHP embedding on Mac](https://gist.github.com/jonnywang/61427ffc0e8dde74fff40f479d147db4)
|
|
|
|
* [SDL bindings](https://pkg.go.dev/github.com/veandco/go-sdl2@v0.4.21/sdl#Main)
|
2022-11-03 08:04:29 +00:00
|
|
|
|
|
|
|
## Docker-Related Resources
|
|
|
|
|
|
|
|
* [Bake file definition](https://docs.docker.com/build/customize/bake/file-definition/)
|
|
|
|
* [docker buildx build](https://docs.docker.com/engine/reference/commandline/buildx_build/)
|