php/archived-frankenphp
1
0
Fork 0
mirror of https://github.com/php/frankenphp.git synced 2026-03-24 00:52:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: improve compilation instructions

Browse Source
This commit is contained in:
Kévin Dunglas
2025-05-30 12:13:58 +02:00
parent c9329bd717
commit 340b1fd1c2
4 changed files with 79 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
README.md
View File

@@ -43,12 +43,6 @@ You can also run command-line scripts with:
frankenphp php-cli /path/to/your/script.php
```
> [!WARNING]
>
> In production, prefer using [the Docker images](#docker), [the Brew package](#homebrew)
> or [compiling FrankenPHP from sources](https://frankenphp.dev/docs/compile/).
> The standalone binary is provided for development and testing purposes.
### Docker
Alternatively, [Docker images](https://frankenphp.dev/docs/docker/) are available:

62
docs/compile.md
View File

@@ -3,13 +3,30 @@
This document explains how to create a FrankenPHP binary that will load PHP as a dynamic library.
This is the recommended method.
Alternatively, [static builds](static.md) can also be created.
Alternatively, [fully and mostly static builds](static.md) can also be created.
## Install PHP
FrankenPHP is compatible with PHP 8.2 and superior.
First, [get the PHP sources](https://www.php.net/downloads.php) and extract them:
### With Homebrew (Linux and Mac)
The easiest way to install a version of libphp compatible with FrankenPHP is to use the ZTS packages provided by [Homebrew PHP](https://github.com/shivammathur/homebrew-php).
First, if not already done, install [Homebrew](https://brew.sh).
Then, install the ZTS variant of PHP, Brotli (optional, for compression support) and watcher (optional, for file change detection):
```console
brew install shivammathur/php/php-zts brotli watcher
brew link --overwrite --force shivammathur/php/php-zts
```
### By Compiling PHP
Alternatively, you can compile PHP from sources with the options needed by FrankenPHP by following these steps.
~~
~~First, [get the PHP sources](https://www.php.net/downloads.php) and extract them:
```console
tar xf php-*
@@ -19,7 +36,7 @@ cd php-*/
Then, run the `configure` script with the options needed for your platform.
The following `./configure` flags are mandatory, but you can add others, for example, to compile extensions or additional features.
### Linux
#### Linux
```console
./configure \
@@ -29,13 +46,12 @@ The following `./configure` flags are mandatory, but you can add others, for exa
--enable-zend-max-execution-timers
```
### Mac
#### Mac
Use the [Homebrew](https://brew.sh/) package manager to install
`libiconv`, `bison`, `re2c` and `pkg-config`:
Use the [Homebrew](https://brew.sh/) package manager to install the required and optional dependencies:
```console
brew install libiconv bison brotli re2c pkg-config
brew install libiconv bison brotli re2c pkg-config watcher
echo 'export PATH="/opt/homebrew/opt/bison/bin:$PATH"' >> ~/.zshrc
```
@@ -43,16 +59,13 @@ Then run the configure script:
```console
./configure \
--enable-embed=static \
--enable-embed \
--enable-zts \
--disable-zend-signals \
--disable-opcache-jit \
--enable-static \
--enable-shared=no \
--with-iconv=/opt/homebrew/opt/libiconv/
```
## Compile PHP
#### Compile PHP
Finally, compile and install PHP:
@@ -67,23 +80,18 @@ Some FrankenPHP features depend on optional system dependencies that must be ins
Alternatively, these features can be disabled by passing build tags to the Go compiler.
| Feature | Dependency | Build tag to disable it |
| ------------------------------ | --------------------------------------------------------------------- | ----------------------- |
|--------------------------------|-----------------------------------------------------------------------|-------------------------|
| Brotli compression | [Brotli](https://github.com/google/brotli) | nobrotli |
| Restart workers on file change | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c) | nowatcher |
## Compile the Go App
You can now build the final binary:
```console
curl -L https://github.com/dunglas/frankenphp/archive/refs/heads/main.tar.gz | tar xz
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build -tags=nobadger,nomysql,nopgx
```
You can now build the final binary.
### Using xcaddy
Alternatively, use [xcaddy](https://github.com/caddyserver/xcaddy) to compile FrankenPHP with [custom Caddy modules](https://caddyserver.com/docs/modules/):
The recommended way is to use [xcaddy](https://github.com/caddyserver/xcaddy) to compile FrankenPHP.
`xcaddy` also allows to easily add [custom Caddy modules](https://caddyserver.com/docs/modules/) and FrankenPHP extensions:
```console
CGO_ENABLED=1 \
@@ -95,7 +103,7 @@ xcaddy build \
--with github.com/dunglas/frankenphp/caddy \
--with github.com/dunglas/mercure/caddy \
--with github.com/dunglas/vulcain/caddy
# Add extra Caddy modules here
# Add extra Caddy modules and FrankenPHP extensions here
```
> [!TIP]
@@ -107,3 +115,13 @@ xcaddy build \
> To do so, change the `XCADDY_GO_BUILD_FLAGS` environment variable to something like
> `XCADDY_GO_BUILD_FLAGS=$'-ldflags "-w -s -extldflags \'-Wl,-z,stack-size=0x80000\'"'`
> (change the stack size value according to your app needs).
### Without xcaddy
Alternatively, it's possible to compile FrankenPHP without `xcaddy` by using the `go` command directly:
```console
curl -L https://github.com/dunglas/frankenphp/archive/refs/heads/main.tar.gz | tar xz
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build -tags=nobadger,nomysql,nopgx
```

6
docs/fr/README.md
View File

@@ -42,12 +42,6 @@ Vous pouvez également exécuter des scripts en ligne de commande avec :
frankenphp php-cli /path/to/your/script.php
```
> [!WARNING]
>
> En production, préférez utiliser [les images Docker](#docker), [le paquet Brew](#homebrew)
> ou [compiler FrankenPHP à partir des sources](https://frankenphp.dev/docs/fr/compile/).
> Le binaire autonome est fourni à des fins de développement et de test.
### Docker
Des [images Docker](https://frankenphp.dev/docs/fr/docker/) sont également disponibles :

60
docs/fr/compile.md
View File

@@ -9,6 +9,23 @@ Alternativement, il est aussi possible de [créer des builds statiques](static.m
FrankenPHP est compatible avec PHP 8.2 et versions ultérieures.
### Avec Homebrew (Linux et Mac)
La manière la plus simple d'installer une version de libphp compatible avec FrankenPHP est d'utiliser les paquets ZTS fournis par [Homebrew PHP](https://github.com/shivammathur/homebrew-php).
Tout d'abord, si ce n'est déjà fait, installez [Homebrew](https://brew.sh).
Ensuite, installez la variante ZTS de PHP, Brotli (facultatif, pour la prise en charge de la compression) et watcher (facultatif, pour la détection des modifications de fichiers) :
```console
brew install shivammathur/php/php-zts brotli watcher
brew link --overwrite --force shivammathur/php/php-zts
```
### En compilant PHP
Vous pouvez également compiler PHP à partir des sources avec les options requises par FrankenPHP en suivant ces étapes.
Tout d'abord, [téléchargez les sources de PHP](https://www.php.net/downloads.php) et extrayez-les :
```console
@@ -32,10 +49,10 @@ Les options de configuration suivantes sont nécessaires pour la compilation, ma
### Mac
Utilisez le gestionnaire de paquets [Homebrew](https://brew.sh/) pour installer `libiconv`, `bison`, `re2c` et `pkg-config` :
Utilisez le gestionnaire de paquets [Homebrew](https://brew.sh/) pour installer les dépendances obligatoires et optionnelles :
```console
brew install libiconv bison brotli re2c pkg-config
brew install libiconv bison brotli re2c pkg-config watcher
echo 'export PATH="/opt/homebrew/opt/bison/bin:$PATH"' >> ~/.zshrc
```
@@ -43,16 +60,14 @@ Puis exécutez le script de configuration :
```console
./configure \
--enable-embed=static \
--enable-embed \
--enable-zts \
--disable-zend-signals \
--disable-opcache-jit \
--enable-static \
--enable-shared=no \
--with-iconv=/opt/homebrew/opt/libiconv/
```
## Compilez PHP
### Compilez PHP
Finalement, compilez et installez PHP :
@@ -64,26 +79,19 @@ sudo make install
## Installez les dépendances optionnelles
Certaines fonctionnalités de FrankenPHP nécessitent des dépendances optionnelles qui doivent être installées.
Ces fonctionnalités peuvent également être désactivées en passant des balises de compilation au compilateur Go.
Ces fonctionnalités peuvent également être désactivées en passant des tags de compilation au compilateur Go.
| Fonctionnalité | Dépendance | Balise de compilation pour la désactiver |
| ------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------- |
| Compression Brotli | [Brotli](https://github.com/google/brotli) | nobrotli |
| Redémarrage des workers en cas de changement de fichier | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c) | nowatcher |
| Fonctionnalité | Dépendance | Tag de compilation pour la désactiver |
|---------------------------------------------------------|-----------------------------------------------------------------------|---------------------------------------|
| Compression Brotli | [Brotli](https://github.com/google/brotli) | nobrotli |
| Redémarrage des workers en cas de changement de fichier | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c) | nowatcher |
## Compiler l'application Go
Vous pouvez maintenant compiler FrankenPHP :
```console
curl -L https://github.com/dunglas/frankenphp/archive/refs/heads/main.tar.gz | tar xz
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build -tags=nobadger,nomysql,nopgx
```
### Utiliser xcaddy
Alternativement, vous pouvez utiliser [xcaddy](https://github.com/caddyserver/xcaddy) pour compiler FrankenPHP avec [des modules Caddy additionnels](https://caddyserver.com/docs/modules/) :
La méthode recommandée consiste à utiliser [xcaddy](https://github.com/caddyserver/xcaddy) pour compiler FrankenPHP.
`xcaddy` permet également d'ajouter facilement des [modules Caddy personnalisés](https://caddyserver.com/docs/modules/) et des extensions FrankenPHP :
```console
CGO_ENABLED=1 \
@@ -96,7 +104,7 @@ xcaddy build \
--with github.com/dunglas/caddy-cbrotli \
--with github.com/dunglas/mercure/caddy \
--with github.com/dunglas/vulcain/caddy
# Add extra Caddy modules here
# Ajoutez les modules Caddy supplémentaires et les extensions FrankenPHP ici
```
> [!TIP]
@@ -108,3 +116,13 @@ xcaddy build \
> Pour ce faire, modifiez la variable d'environnement `XCADDY_GO_BUILD_FLAGS` en quelque chose comme
> `XCADDY_GO_BUILD_FLAGS=$'-ldflags "-w -s -extldflags \'-Wl,-z,stack-size=0x80000\'"'`
> (modifiez la valeur de la taille de la pile selon les besoins de votre application).
### Sans xcaddy
Il est également possible de compiler FrankenPHP sans `xcaddy` en utilisant directement la commande `go` :
```console
curl -L https://github.com/dunglas/frankenphp/archive/refs/heads/main.tar.gz | tar xz
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build -tags=nobadger,nomysql,nopgx
```