diff --git a/.github/workflows/windows.yaml b/.github/workflows/windows.yaml index bba4a8402..ecff99064 100644 --- a/.github/workflows/windows.yaml +++ b/.github/workflows/windows.yaml @@ -217,7 +217,7 @@ jobs: "opcache.enable=0`r`nopcache.enable_cli=0" | Out-File php.ini $env:PHPRC = Get-Location - go test ./... + go test -race ./... cd caddy - go test ./... + go test -race ./... working-directory: ${{ github.workspace }}\frankenphp diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 73d8b19ab..009c561f1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ The image contains the usual development tools (Go, GDB, Valgrind, Neovim...) an - additional configuration files: `/etc/frankenphp/php.d/*.ini` - php extensions: `/usr/lib/frankenphp/modules/` -If your Docker version is lower than 23.0, the build will fail due to dockerignore [pattern issue](https://github.com/moby/moby/pull/42676). Add directories to `.dockerignore`. +If your Docker version is lower than 23.0, the build will fail due to dockerignore [pattern issue](https://github.com/moby/moby/pull/42676). Add directories to `.dockerignore`: ```patch !testdata/*.php @@ -30,14 +30,14 @@ If your Docker version is lower than 23.0, the build will fail due to dockerigno [Follow the instructions to compile from sources](https://frankenphp.dev/docs/compile/) and pass the `--debug` configuration flag. -## Running the test suite +## Running the Test Suite ```console -export CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" +export CGO_CFLAGS=-O0 -g $(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go test -race -v ./... ``` -## Caddy module +## Caddy Module Build Caddy with the FrankenPHP Caddy module: @@ -57,13 +57,13 @@ cd testdata/ The server is listening on `127.0.0.1:80`: > [!NOTE] -> if you are using Docker, you will have to either bind container port 80 or execute from inside the container +> If you are using Docker, you will have to either bind container port 80 or execute from inside the container ```console curl -vk http://127.0.0.1/phpinfo.php ``` -## Minimal test server +## Minimal Test Server Build the minimal test server: @@ -86,9 +86,76 @@ The server is listening on `127.0.0.1:8080`: curl -v http://127.0.0.1:8080/phpinfo.php ``` +## Windows Development + +1. Configure Git to always use `lf` line endings + + ```powershell + git config --global core.autocrlf false + git config --global core.eol lf + ``` + +2. Install Visual Studio, Git, and Go: + + ```powershell + winget install -e --id Microsoft.VisualStudio.2022.Community --override "--passive --wait --add Microsoft.VisualStudio.Workload.NativeDesktop --add Microsoft.VisualStudio.Component.VC.Llvm.Clang --includeRecommended" + winget install -e --id GoLang.Go + winget install -e --id Git.Git + ``` + +3. Install vcpkg: + + ```powershell + cd C:\ + git clone https://github.com/microsoft/vcpkg + .\vcpkg\bootstrap-vcpkg.bat + ``` + +4. [Download the latest version of the watcher library for Windows](https://github.com/e-dant/watcher/releases) and extract it to a directory named `C:\watcher` +5. [Download the latest **Thread Safe** version of PHP and of the PHP SDK for Windows](https://windows.php.net/download/), extract them in directories named `C:\php` and `C:\php-devel` +6. Clone the FrankenPHP Git repository: + + ```powershell + git clone https://github.com/php/frankenphp C:\frankenphp + cd C:\frankenphp + ``` + +7. Install the dependencies: + + ```powershell + C:\vcpkg\vcpkg.exe install + ``` + +8. Configure the needed environment variables (PowerShell): + + ```powershell + $env:PATH += ';C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\Llvm\bin' + $env:CC = 'clang' + $env:CXX = 'clang++' + $env:CGO_CFLAGS = "-O0 -g -IC:\frankenphp\vcpkg_installed\x64-windows\include -IC:\watcher -IC:\php-devel\include -IC:\php-devel\include\main -IC:\php-devel\include\TSRM -IC:\php-devel\include\Zend -IC:\php-devel\include\ext" + $env:CGO_LDFLAGS = '-LC:\frankenphp\vcpkg_installed\x64-windows\lib -lbrotlienc -LC:\watcher -llibwatcher-c -LC:\php -LC:\php-devel\lib -lphp8ts -lphp8embed' + ``` + +9. Run the tests: + + ```powershell + go test -race -ldflags '-extldflags="-fuse-ld=lld"' ./... + cd caddy + go test -race -ldflags '-extldflags="-fuse-ld=lld"' -tags nobadger,nomysql,nopgx ./... + cd .. + ``` + +10. Build the binary: + + ```powershell + cd caddy/frankenphp + go build -ldflags '-extldflags="-fuse-ld=lld"' -tags nobadger,nomysql,nopgx + cd ../.. + ``` + ## Building Docker Images Locally -Print bake plan: +Print Bake plan: ```console docker buildx bake -f docker-bake.hcl --print @@ -125,7 +192,7 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push docker cp $(docker create --name static-builder-musl dunglas/frankenphp:static-builder-musl):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp ``` -2. Replace your current version of `frankenphp` by the debug FrankenPHP executable +2. Replace your current version of `frankenphp` with 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: @@ -155,7 +222,7 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push ```patch - name: Set CGO flags - run: echo "CGO_CFLAGS=$(php-config --includes)" >> "$GITHUB_ENV" + run: echo "CGO_CFLAGS=-O0 -g $(php-config --includes)" >> "$GITHUB_ENV" + - run: | + sudo apt install gdb + mkdir -p /home/runner/.config/gdb/ @@ -207,7 +274,7 @@ strace -e 'trace=!futex,epoll_ctl,epoll_pwait,tgkill,rt_sigreturn' -p 1 ## Translating the Documentation -To translate the documentation and the site in a new language, +To translate the documentation and the site into 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 @@ -215,6 +282,6 @@ follow these steps: 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 translate strings starting with `> [!` (it's special markup for GitHub) 5. Create a Pull Request with the translations -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 +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 7. Translate the values in the created YAML file 8. Open a Pull Request on the site repository