2021-09-24 16:52:20 +00:00
# Contributing
2022-10-19 09:19:49 +00:00
## Compiling PHP
2023-12-01 16:26:21 +00:00
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-12-01 16:26:21 +00:00
```console
docker build -t frankenphp-dev -f dev.Dockerfile .
2024-01-20 10:49:16 +00:00
docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined -p 8080:8080 -p 443:443 -p 443:443/udp -v $PWD:/go/src/app -it frankenphp-dev
2023-12-01 16:26:21 +00:00
```
2022-10-04 12:36:03 +00:00
2023-10-10 08:20:57 +00:00
The image contains the usual development tools (Go, GDB, Valgrind, Neovim...).
2023-12-01 16:26:21 +00:00
2023-10-10 08:20:57 +00:00
If docker version is lower than 23.0, build is failed by dockerignore [pattern issue ](https://github.com/moby/moby/pull/42676 ). Add directories to `.dockerignore` .
2023-12-01 16:26:21 +00:00
2023-10-10 08:20:57 +00:00
```patch
!testdata/*.php
!testdata/*.txt
+!caddy
+!C-Thread-Pool
+!internal
```
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
2023-12-06 23:01:51 +00:00
[Follow the instructions to compile from sources ](https://frankenphp.dev/docs/compile/ ) 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
2023-12-01 16:26:21 +00:00
```console
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
2023-12-01 16:26:21 +00:00
```console
cd caddy/frankenphp/
go build
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
2023-12-01 16:26:21 +00:00
```console
cd testdata/
../caddy/frankenphp/frankenphp run
```
2022-10-04 12:36:03 +00:00
The server is listening on `127.0.0.1:8080` :
2023-12-01 16:26:21 +00:00
```console
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:
2023-12-01 16:26:21 +00:00
```console
cd internal/testserver/
go build
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
2023-12-01 16:26:21 +00:00
```console
cd testdata/
../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` :
2023-12-01 16:26:21 +00:00
```console
curl -v http://127.0.0.1:8080/phpinfo.php
```
2022-10-19 09:19:49 +00:00
2023-12-01 16:26:21 +00:00
## Building Docker Images Locally
2022-11-03 08:04:29 +00:00
Print bake plan:
2023-12-01 16:26:21 +00:00
```console
2022-11-03 08:04:29 +00:00
docker buildx bake -f docker-bake.hcl --print
```
Build FrankenPHP images for amd64 locally:
2023-12-01 16:26:21 +00:00
```console
2022-11-03 08:04:29 +00:00
docker buildx bake -f docker-bake.hcl --pull --load --set "*.platform=linux/amd64"
```
Build FrankenPHP images for arm64 locally:
2023-12-01 16:26:21 +00:00
```console
2022-11-03 08:04:29 +00:00
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:
2023-12-01 16:26:21 +00:00
```console
2022-11-03 08:04:29 +00:00
docker buildx bake -f docker-bake.hcl --pull --no-cache --push
```
2024-03-08 09:40:20 +00:00
## Debugging Segmentation Faults With Static Builds
1. Download the debug version of the FrankenPHP binary from GitHub or create your custom static build inlcuidng debug symbols:
```console
docker buildx bake \
--load \
--set static-builder.args.DEBUG_SYMBOLS=1 \
--set "static-builder.platform=linux/amd64" \
static-builder
docker cp $(docker create --name static-builder dunglas/frankenphp:static-builder):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
```
2. Replace your current version of `frankenphp` by the debug FrankenPHP executable
3. Start FrankenPHP as usual (alternatively, you can directly start FrankenPHP with GDB: `gdb --args ./frankenphp run` )
4. Attach to the process with GDB:
```console
gdb -p `pidof frankenphp`
```
5. If necessary, type `continue` in the GDB shell
6. Make FrankenPHP crash
7. Type `bt` in the GDB shell
8. Copy the output
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
2023-12-01 16:26:21 +00:00
2023-07-10 10:00:15 +00:00
```patch
- uses: shivammathur/setup-php@v2
# ...
env:
phpts: ts
+ debug: true
```
2023-12-01 16:26:21 +00:00
2023-07-10 10:00:15 +00:00
3. Enable `tmate` to connect to the container
2023-12-01 16:26:21 +00:00
2023-07-10 10:00:15 +00:00
```patch
2023-11-15 15:41:44 +00:00
-
name: Set CGO flags
2023-07-10 10:00:15 +00:00
run: echo "CGO_CFLAGS=$(php-config --includes)" >> "$GITHUB_ENV"
2023-11-15 15:41:44 +00:00
+ -
+ run: |
+ sudo apt install gdb
2023-07-10 10:00:15 +00:00
+ mkdir -p /home/runner/.config/gdb/
+ printf "set auto-load safe-path /\nhandle SIG34 nostop noprint pass" > /home/runner/.config/gdb/gdbinit
2023-11-15 15:41:44 +00:00
+ -
+ uses: mxschmitt/action-tmate@v3
2023-07-10 10:00:15 +00:00
```
2023-12-01 16:26:21 +00:00
2023-11-15 15:41:44 +00:00
4. Connect to the container
5. Open `frankenphp.go`
6. Enable `cgosymbolizer`
2023-12-01 16:26:21 +00:00
2023-07-10 10:00:15 +00:00
```patch
- //_ "github.com/ianlancetaylor/cgosymbolizer"
+ _ "github.com/ianlancetaylor/cgosymbolizer"
```
2023-12-01 16:26:21 +00:00
2023-11-15 15:41:44 +00:00
7. Download the module: `go get`
8. In the container, you can use GDB and the like:
2023-12-01 16:26:21 +00:00
```console
2023-07-10 10:00:15 +00:00
go test -c -ldflags=-w
gdb --args ./frankenphp.test -test.run ^MyTest$
```
2023-12-01 16:26:21 +00:00
2023-11-15 15:41:44 +00:00
9. When the bug is fixed, revert all these changes
2023-07-10 10:00:15 +00:00
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/ )
2023-09-17 18:29:43 +00:00
## Useful Command
2023-12-01 16:26:21 +00:00
```console
2023-09-17 18:29:43 +00:00
apk add strace util-linux gdb
strace -e 'trace=!futex,epoll_ctl,epoll_pwait,tgkill,rt_sigreturn' -p 1
2023-10-10 08:20:57 +00:00
```
2024-03-13 16:24:26 +00:00
## Translating the Documentation
To translate the documentation and the site in a new language,
follow these steps:
1. Create a new directory named with the language's 2-character ISO code in this repository's `docs/` directory
2. Copy all the `.md` files in the root of the `docs/` directory into the new directory (always use the English version as source for translation, as it's always up to date)
3. Copy the `README.md` and `CONTRIBUTING.md` files from the root directory to the new directory
4. Translate the content of the files, but don't change the filenames, also don't translates strings starting with `> [!` (it's special markup for GitHub)
5. Create a Pull Request with the translations
2024-03-18 09:34:53 +00:00
6. In the [site repository ](https://github.com/dunglas/frankenphp-website/tree/main ), copy and translate the translation files in the `content/` , `data/` and `i18n/` directories
2024-03-13 16:24:26 +00:00
7. Translate the values in the created YAML file
8. Open a Pull Request on the site repository