From 340b1fd1c24a76d4e2cef781952e0996fce37c0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Dunglas?= Date: Fri, 30 May 2025 12:13:58 +0200 Subject: [PATCH] docs: improve compilation instructions --- README.md | 6 ----- docs/compile.md | 62 ++++++++++++++++++++++++++++++---------------- docs/fr/README.md | 6 ----- docs/fr/compile.md | 60 ++++++++++++++++++++++++++++---------------- 4 files changed, 79 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 63a8c774..0f00beee 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/compile.md b/docs/compile.md index 9e2e0bde..e2c4af82 100644 --- a/docs/compile.md +++ b/docs/compile.md @@ -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 +``` diff --git a/docs/fr/README.md b/docs/fr/README.md index 427824f8..789b643c 100644 --- a/docs/fr/README.md +++ b/docs/fr/README.md @@ -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 : diff --git a/docs/fr/compile.md b/docs/fr/compile.md index 5c039abc..e7f7bd7b 100644 --- a/docs/fr/compile.md +++ b/docs/fr/compile.md @@ -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 +```