From 82abe1beea3ac6304343f7751a33c11db8ab81c0 Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Tue, 5 Aug 2025 12:10:04 +0700
Subject: [PATCH 01/10] add basic IDE setup to docs (WIP)

---
 .gitignore          |   1 +
 docs/development.md | 142 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 143 insertions(+)
 create mode 100644 docs/development.md

diff --git a/.gitignore b/.gitignore
index 21bd3b59b..79dd87542 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,4 @@ frankenphp.test
 caddy/frankenphp/Build
 package/etc/php.ini
 *.log
+compile_flags.txt
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 000000000..b45a4050f
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,142 @@
+# FrankenPHP Development Environment Setup
+
+---
+
+## For Windows: WSL2 Setup with X11 GUI Support
+
+1. Install WSL2:
+
+   ```powershell
+   wsl --install
+   ```
+2. Install a Linux distribution (example: AlmaLinux 10) via e.g. `wsl --install AlmaLinux-10`.
+3. Install X11 dependencies to run GUI-based IDEs from within WSL2:
+
+   ```bash
+   sudo dnf install libXtst libXi libXrender libXrandr libXcursor libXinerama libXcomposite libXdamage libXext libXfixes
+   ```
+
+---
+
+## Initial setup
+
+Follow the guide on [compiling from sources](compile.md).
+We will assume you installed these things into the following paths: 
+- go: `/usr/local/go`
+- cloned `~/php-src`
+- php: `/usr/local/bin/php`
+- cloned `~/frankenphp`
+
+## CLion Setup for CGO glue/PHP Source Development
+
+### 1. Install CLion
+
+* Download from: [https://www.jetbrains.com/clion/download/](https://www.jetbrains.com/clion/download/)
+* Extract and install:
+
+  ```bash
+  tar -xzf CLion-*.tar.gz
+  sudo mv clion-* /opt/clion
+  ```
+* Launch:
+
+  ```bash
+  /opt/clion/bin/clion &>/dev/null
+  ```
+
+### 2. Open Project in CLion
+
+* Open CLion → Open → Select the `~/frankenphp` directory
+* Add a build chain: Settings → Build, Execution, Deployment → Custom Build Targets
+* Select any Build Target, under `Build` set up an External Tool (call it e.g. go build)
+* Set up a wrapper script that builds frankenphp for you, called `go_compile_frankenphp.sh`
+
+```bash
+export CGO_CFLAGS="-O0 -g $(php-config --includes)"
+export CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)"
+go build -tags=nobadger,nomysql,nopgx
+```
+
+* Under Program, select `go_compile_frankenphp.sh`
+* Leave Arguments blank
+* Working Directory: `~/frankenphp/caddy/frankenphp`
+
+### 3. Configure Run Targets
+
+* Go to **Run → Edit Configurations**
+* Create:
+
+   * **frankenphp**:
+
+      * Type: Native Application
+      * Target: select the `go build` target you created
+      * Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
+      * Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
+
+### 4. Debug Go files from CLion
+
+* Right click on a *.go file in the Project view on the left
+* Override file type
+* C/C++
+
+Now you can place breakpoints in C, C++ and Go files.
+To get syntax highlighting for imports from php-src, you may need to tell CLion about the include paths. Create a `compile_flags.txt` file in `~/frankenphp` with the following contents:
+
+```gcc
+-I/usr/local/include/php
+-I/usr/local/include/php/Zend
+-I/usr/local/include/php/main
+-I/usr/local/include/php/TSRM
+```
+
+---
+
+## GoLand Setup for FrankenPHP Development
+
+Use GoLand for primary Go development, but the debugger cannot debug C code.
+
+### 1. Install GoLand
+
+* Download from: [https://www.jetbrains.com/go/download/](https://www.jetbrains.com/go/download/)
+* Extract and install:
+
+  ```bash
+  tar -xzf goland-*.tar.gz
+  sudo mv GoLand-* /opt/goland
+  ```
+* Launch:
+
+  ```bash
+  /opt/goland/bin/goland &>/dev/null
+  ```
+
+### 2. Open in GoLand
+
+* Launch GoLand → Open → Select the `~/frankenphp` directory
+
+---
+
+### Go Configuration
+
+* Select Go Build
+   * Name `frankenphp`
+   * Run kind: Directory
+
+* Directory: `~/frankenphp/caddy/frankenphp`
+* Output directory: `~/frankenphp/caddy/frankenphp`
+* Working directory: `~/frankenphp/caddy/frankenphp`
+* Environment (adjust for your $(php-config ...) output): `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
+* Go tool arguments: `-tags=nobadger,nomysql,nopgx`
+* Program arguments: e.g. `php-cli -i`
+
+You can now place breakpoints and debug through Go code when you debug the `frankenphp` configuration, but breakpoints in C code will not work.
+
+---
+
+## Debugging and Integration Notes
+
+* Use **CLion** for debugging PHP internals and `cgo` glue code
+* Use **GoLand** for primary Go development and debugging
+* FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting won't work in Go files
+
+---
\ No newline at end of file

From 8e51d5df3eeef88a12e3aeae6c76ffb56ee8442c Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:00:02 +0700
Subject: [PATCH 02/10] use windows installed ides

---
 docs/development.md | 27 ++++++---------------------
 1 file changed, 6 insertions(+), 21 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index b45a4050f..9b685b203 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -10,11 +10,6 @@
    wsl --install
    ```
 2. Install a Linux distribution (example: AlmaLinux 10) via e.g. `wsl --install AlmaLinux-10`.
-3. Install X11 dependencies to run GUI-based IDEs from within WSL2:
-
-   ```bash
-   sudo dnf install libXtst libXi libXrender libXrandr libXcursor libXinerama libXcomposite libXdamage libXext libXfixes
-   ```
 
 ---
 
@@ -29,19 +24,14 @@ We will assume you installed these things into the following paths:
 
 ## CLion Setup for CGO glue/PHP Source Development
 
-### 1. Install CLion
+### 1. Install CLion (on your host OS)
 
 * Download from: [https://www.jetbrains.com/clion/download/](https://www.jetbrains.com/clion/download/)
-* Extract and install:
 
-  ```bash
-  tar -xzf CLion-*.tar.gz
-  sudo mv clion-* /opt/clion
-  ```
-* Launch:
+* Launch (if on Windows, in WSL):
 
   ```bash
-  /opt/clion/bin/clion &>/dev/null
+  clion &>/dev/null
   ```
 
 ### 2. Open Project in CLion
@@ -95,19 +85,14 @@ To get syntax highlighting for imports from php-src, you may need to tell CLion
 
 Use GoLand for primary Go development, but the debugger cannot debug C code.
 
-### 1. Install GoLand
+### 1. Install GoLand (on your host OS)
 
 * Download from: [https://www.jetbrains.com/go/download/](https://www.jetbrains.com/go/download/)
-* Extract and install:
 
-  ```bash
-  tar -xzf goland-*.tar.gz
-  sudo mv GoLand-* /opt/goland
-  ```
-* Launch:
+* Launch (if on Windows, in WSL):
 
   ```bash
-  /opt/goland/bin/goland &>/dev/null
+  goland &>/dev/null
   ```
 
 ### 2. Open in GoLand

From c0f07a19a459721d691d61e1b6d81f70ed0808e7 Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:01:26 +0700
Subject: [PATCH 03/10] remove thingy

---
 docs/development.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/development.md b/docs/development.md
index 9b685b203..cf67e9fba 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -2,7 +2,7 @@
 
 ---
 
-## For Windows: WSL2 Setup with X11 GUI Support
+## For Windows: WSL2 Setup
 
 1. Install WSL2:
 

From a7c3001d157abed2ea862252935f884776f7f65a Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:03:20 +0700
Subject: [PATCH 04/10] markdown linter

---
 docs/development.md | 70 +++++++++++++++++++++++----------------------
 1 file changed, 36 insertions(+), 34 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index cf67e9fba..5740b6788 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -9,6 +9,7 @@
    ```powershell
    wsl --install
    ```
+
 2. Install a Linux distribution (example: AlmaLinux 10) via e.g. `wsl --install AlmaLinux-10`.
 
 ---
@@ -17,6 +18,7 @@
 
 Follow the guide on [compiling from sources](compile.md).
 We will assume you installed these things into the following paths: 
+
 - go: `/usr/local/go`
 - cloned `~/php-src`
 - php: `/usr/local/bin/php`
@@ -26,9 +28,9 @@ We will assume you installed these things into the following paths:
 
 ### 1. Install CLion (on your host OS)
 
-* Download from: [https://www.jetbrains.com/clion/download/](https://www.jetbrains.com/clion/download/)
+- Download from: [https://www.jetbrains.com/clion/download/](https://www.jetbrains.com/clion/download/)
 
-* Launch (if on Windows, in WSL):
+- Launch (if on Windows, in WSL):
 
   ```bash
   clion &>/dev/null
@@ -36,10 +38,10 @@ We will assume you installed these things into the following paths:
 
 ### 2. Open Project in CLion
 
-* Open CLion → Open → Select the `~/frankenphp` directory
-* Add a build chain: Settings → Build, Execution, Deployment → Custom Build Targets
-* Select any Build Target, under `Build` set up an External Tool (call it e.g. go build)
-* Set up a wrapper script that builds frankenphp for you, called `go_compile_frankenphp.sh`
+- Open CLion → Open → Select the `~/frankenphp` directory
+- Add a build chain: Settings → Build, Execution, Deployment → Custom Build Targets
+- Select any Build Target, under `Build` set up an External Tool (call it e.g. go build)
+- Set up a wrapper script that builds frankenphp for you, called `go_compile_frankenphp.sh`
 
 ```bash
 export CGO_CFLAGS="-O0 -g $(php-config --includes)"
@@ -47,27 +49,27 @@ export CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)"
 go build -tags=nobadger,nomysql,nopgx
 ```
 
-* Under Program, select `go_compile_frankenphp.sh`
-* Leave Arguments blank
-* Working Directory: `~/frankenphp/caddy/frankenphp`
+- Under Program, select `go_compile_frankenphp.sh`
+- Leave Arguments blank
+- Working Directory: `~/frankenphp/caddy/frankenphp`
 
 ### 3. Configure Run Targets
 
-* Go to **Run → Edit Configurations**
-* Create:
+- Go to **Run → Edit Configurations**
+- Create:
 
-   * **frankenphp**:
+   - **frankenphp**:
 
-      * Type: Native Application
-      * Target: select the `go build` target you created
-      * Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
-      * Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
+      - Type: Native Application
+      - Target: select the `go build` target you created
+      - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
+      - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
 
 ### 4. Debug Go files from CLion
 
-* Right click on a *.go file in the Project view on the left
-* Override file type
-* C/C++
+- Right click on a *.go file in the Project view on the left
+- Override file type
+- C/C++
 
 Now you can place breakpoints in C, C++ and Go files.
 To get syntax highlighting for imports from php-src, you may need to tell CLion about the include paths. Create a `compile_flags.txt` file in `~/frankenphp` with the following contents:
@@ -87,9 +89,9 @@ Use GoLand for primary Go development, but the debugger cannot debug C code.
 
 ### 1. Install GoLand (on your host OS)
 
-* Download from: [https://www.jetbrains.com/go/download/](https://www.jetbrains.com/go/download/)
+- Download from: [https://www.jetbrains.com/go/download/](https://www.jetbrains.com/go/download/)
 
-* Launch (if on Windows, in WSL):
+- Launch (if on Windows, in WSL):
 
   ```bash
   goland &>/dev/null
@@ -97,22 +99,22 @@ Use GoLand for primary Go development, but the debugger cannot debug C code.
 
 ### 2. Open in GoLand
 
-* Launch GoLand → Open → Select the `~/frankenphp` directory
+- Launch GoLand → Open → Select the `~/frankenphp` directory
 
 ---
 
 ### Go Configuration
 
-* Select Go Build
-   * Name `frankenphp`
-   * Run kind: Directory
+- Select Go Build
+   - Name `frankenphp`
+   - Run kind: Directory
 
-* Directory: `~/frankenphp/caddy/frankenphp`
-* Output directory: `~/frankenphp/caddy/frankenphp`
-* Working directory: `~/frankenphp/caddy/frankenphp`
-* Environment (adjust for your $(php-config ...) output): `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
-* Go tool arguments: `-tags=nobadger,nomysql,nopgx`
-* Program arguments: e.g. `php-cli -i`
+- Directory: `~/frankenphp/caddy/frankenphp`
+- Output directory: `~/frankenphp/caddy/frankenphp`
+- Working directory: `~/frankenphp/caddy/frankenphp`
+- Environment (adjust for your $(php-config ...) output): `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
+- Go tool arguments: `-tags=nobadger,nomysql,nopgx`
+- Program arguments: e.g. `php-cli -i`
 
 You can now place breakpoints and debug through Go code when you debug the `frankenphp` configuration, but breakpoints in C code will not work.
 
@@ -120,8 +122,8 @@ You can now place breakpoints and debug through Go code when you debug the `fran
 
 ## Debugging and Integration Notes
 
-* Use **CLion** for debugging PHP internals and `cgo` glue code
-* Use **GoLand** for primary Go development and debugging
-* FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting won't work in Go files
+- Use **CLion** for debugging PHP internals and `cgo` glue code
+- Use **GoLand** for primary Go development and debugging
+- FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting won't work in Go files
 
 ---
\ No newline at end of file

From 7a1e10ee0377c1a3bfdf65e3be63a44781c9c81f Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:03:46 +0700
Subject: [PATCH 05/10] markdown linter 2

---
 docs/development.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index 5740b6788..221a27701 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -17,7 +17,7 @@
 ## Initial setup
 
 Follow the guide on [compiling from sources](compile.md).
-We will assume you installed these things into the following paths: 
+We will assume you installed these things into the following paths:
 
 - go: `/usr/local/go`
 - cloned `~/php-src`
@@ -58,12 +58,12 @@ go build -tags=nobadger,nomysql,nopgx
 - Go to **Run → Edit Configurations**
 - Create:
 
-   - **frankenphp**:
+    - **frankenphp**:
 
-      - Type: Native Application
-      - Target: select the `go build` target you created
-      - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
-      - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
+        - Type: Native Application
+        - Target: select the `go build` target you created
+        - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
+        - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
 
 ### 4. Debug Go files from CLion
 
@@ -72,7 +72,8 @@ go build -tags=nobadger,nomysql,nopgx
 - C/C++
 
 Now you can place breakpoints in C, C++ and Go files.
-To get syntax highlighting for imports from php-src, you may need to tell CLion about the include paths. Create a `compile_flags.txt` file in `~/frankenphp` with the following contents:
+To get syntax highlighting for imports from php-src, you may need to tell CLion about the include paths. Create a
+`compile_flags.txt` file in `~/frankenphp` with the following contents:
 
 ```gcc
 -I/usr/local/include/php
@@ -106,17 +107,19 @@ Use GoLand for primary Go development, but the debugger cannot debug C code.
 ### Go Configuration
 
 - Select Go Build
-   - Name `frankenphp`
-   - Run kind: Directory
+    - Name `frankenphp`
+    - Run kind: Directory
 
 - Directory: `~/frankenphp/caddy/frankenphp`
 - Output directory: `~/frankenphp/caddy/frankenphp`
 - Working directory: `~/frankenphp/caddy/frankenphp`
-- Environment (adjust for your $(php-config ...) output): `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
+- Environment (adjust for your $(php-config ...) output):
+  `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
 - Go tool arguments: `-tags=nobadger,nomysql,nopgx`
 - Program arguments: e.g. `php-cli -i`
 
-You can now place breakpoints and debug through Go code when you debug the `frankenphp` configuration, but breakpoints in C code will not work.
+You can now place breakpoints and debug through Go code when you debug the `frankenphp` configuration, but breakpoints
+in C code will not work.
 
 ---
 
@@ -124,6 +127,7 @@ You can now place breakpoints and debug through Go code when you debug the `fran
 
 - Use **CLion** for debugging PHP internals and `cgo` glue code
 - Use **GoLand** for primary Go development and debugging
-- FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting won't work in Go files
+- FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting
+  won't work in Go files
 
 ---
\ No newline at end of file

From a51c7ae8261f02b7f7b8c0e09334ad45a7234e20 Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:21:47 +0700
Subject: [PATCH 06/10] markdown linter 3

---
 docs/development.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index 221a27701..bec85d4ae 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -58,12 +58,12 @@ go build -tags=nobadger,nomysql,nopgx
 - Go to **Run → Edit Configurations**
 - Create:
 
-    - **frankenphp**:
+  - **frankenphp**:
 
-        - Type: Native Application
-        - Target: select the `go build` target you created
-        - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
-        - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
+    - Type: Native Application
+    - Target: select the `go build` target you created
+    - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
+    - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
 
 ### 4. Debug Go files from CLion
 
@@ -130,4 +130,4 @@ in C code will not work.
 - FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting
   won't work in Go files
 
----
\ No newline at end of file
+---

From 7b0966df8821e634deb31b14e73b2ef8e381371a Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:25:27 +0700
Subject: [PATCH 07/10] markdown linter 4

---
 docs/development.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index bec85d4ae..654438025 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -107,8 +107,8 @@ Use GoLand for primary Go development, but the debugger cannot debug C code.
 ### Go Configuration
 
 - Select Go Build
-    - Name `frankenphp`
-    - Run kind: Directory
+  - Name `frankenphp`
+  - Run kind: Directory
 
 - Directory: `~/frankenphp/caddy/frankenphp`
 - Output directory: `~/frankenphp/caddy/frankenphp`

From 54faf79466c693bd34047323fb81c87ed08363db Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 17:41:52 +0700
Subject: [PATCH 08/10] reword

---
 docs/development.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index 654438025..208f8c028 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -4,25 +4,25 @@
 
 ## For Windows: WSL2 Setup
 
+FrankenPHP cannot be compiled natively on Windows, so to build and debug code, you need to run your IDE's in WSL.
+
 1. Install WSL2:
 
    ```powershell
    wsl --install
    ```
 
-2. Install a Linux distribution (example: AlmaLinux 10) via e.g. `wsl --install AlmaLinux-10`.
-
 ---
 
 ## Initial setup
 
-Follow the guide on [compiling from sources](compile.md).
-We will assume you installed these things into the following paths:
+Follow the instructions in [compiling from sources](compile.md).
+The steps assume the following environment:
 
-- go: `/usr/local/go`
-- cloned `~/php-src`
-- php: `/usr/local/bin/php`
-- cloned `~/frankenphp`
+- Go installed at `/usr/local/go`
+- PHP source cloned to `~/php-src`
+- PHP built at: `/usr/local/bin/php`
+- FrankenPHP source cloned to `~/frankenphp`
 
 ## CLion Setup for CGO glue/PHP Source Development
 

From 2bdda86480560c1959a974e502690a96c9781037 Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 18:31:16 +0700
Subject: [PATCH 09/10] move docs to CONTRIBUTING.md

---
 CONTRIBUTING.md     | 125 +++++++++++++++++++++++++++++++++++++++++
 docs/development.md | 133 --------------------------------------------
 2 files changed, 125 insertions(+), 133 deletions(-)
 delete mode 100644 docs/development.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4217589c5..48775a3fb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -181,6 +181,131 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 
 9. When the bug is fixed, revert all these changes
 
+## Development Environment Setup
+
+---
+
+### For Windows: WSL2 Setup
+
+FrankenPHP cannot be compiled natively on Windows, so to build and debug code, you need to run your IDE in WSL.
+
+1. Install WSL2:
+
+   ```powershell
+   wsl --install
+   ```
+
+---
+
+### Initial setup
+
+Follow the instructions in [compiling from sources](https://frankenphp.dev/docs/compile/).
+The steps assume the following environment:
+
+- Go installed at `/usr/local/go`
+- PHP source cloned to `~/php-src`
+- PHP built at: `/usr/local/bin/php`
+- FrankenPHP source cloned to `~/frankenphp`
+
+### CLion Setup for CGO glue/PHP Source Development
+
+1. Install CLion (on your host OS)
+
+   - Download from: https://www.jetbrains.com/clion/download/
+   - Launch (if on Windows, in WSL):
+
+     ```bash
+     clion &>/dev/null
+     ```
+
+2. Open Project in CLion
+
+   - Open CLion → Open → Select the `~/frankenphp` directory
+   - Add a build chain: Settings → Build, Execution, Deployment → Custom Build Targets
+   - Select any Build Target, under `Build` set up an External Tool (call it e.g. go build)
+   - Set up a wrapper script that builds frankenphp for you, called `go_compile_frankenphp.sh`
+
+   ```bash
+   export CGO_CFLAGS="-O0 -g $(php-config --includes)"
+   export CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)"
+   go build -tags=nobadger,nomysql,nopgx
+   ```
+
+   - Under Program, select `go_compile_frankenphp.sh`
+   - Leave Arguments blank
+   - Working Directory: `~/frankenphp/caddy/frankenphp`
+
+3. Configure Run Targets
+
+   - Go to Run → Edit Configurations
+   - Create:
+     - frankenphp:
+       - Type: Native Application
+       - Target: select the `go build` target you created
+       - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
+       - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
+
+4. Debug Go files from CLion
+
+   - Right click on a *.go file in the Project view on the left
+   - Override file type → C/C++
+
+   Now you can place breakpoints in C, C++ and Go files.
+   To get syntax highlighting for imports from php-src, you may need to tell CLion about the include paths. Create a
+   `compile_flags.txt` file in `~/frankenphp` with the following contents:
+
+   ```gcc
+   -I/usr/local/include/php
+   -I/usr/local/include/php/Zend
+   -I/usr/local/include/php/main
+   -I/usr/local/include/php/TSRM
+   ```
+
+---
+
+### GoLand Setup for FrankenPHP Development
+
+Use GoLand for primary Go development, but the debugger cannot debug C code.
+
+1. Install GoLand (on your host OS)
+
+   - Download from: https://www.jetbrains.com/go/download/
+   - Launch (if on Windows, in WSL):
+
+     ```bash
+     goland &>/dev/null
+     ```
+
+2. Open in GoLand
+
+   - Launch GoLand → Open → Select the `~/frankenphp` directory
+
+---
+
+### Go Configuration
+
+- Select Go Build
+  - Name `frankenphp`
+  - Run kind: Directory
+- Directory: `~/frankenphp/caddy/frankenphp`
+- Output directory: `~/frankenphp/caddy/frankenphp`
+- Working directory: `~/frankenphp/caddy/frankenphp`
+- Environment (adjust for your $(php-config ...) output):
+  `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
+- Go tool arguments: `-tags=nobadger,nomysql,nopgx`
+- Program arguments: e.g. `php-cli -i`
+
+You can now place breakpoints and debug through Go code when you debug the `frankenphp` configuration, but breakpoints
+in C code will not work.
+
+---
+
+### Debugging and Integration Notes
+
+- Use CLion for debugging PHP internals and `cgo` glue code
+- Use GoLand for primary Go development and debugging
+- FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting won't work in Go files
+
 ## Misc Dev Resources
 
 - [PHP embedding in uWSGI](https://github.com/unbit/uwsgi/blob/master/plugins/php/php_plugin.c)
diff --git a/docs/development.md b/docs/development.md
deleted file mode 100644
index 208f8c028..000000000
--- a/docs/development.md
+++ /dev/null
@@ -1,133 +0,0 @@
-# FrankenPHP Development Environment Setup
-
----
-
-## For Windows: WSL2 Setup
-
-FrankenPHP cannot be compiled natively on Windows, so to build and debug code, you need to run your IDE's in WSL.
-
-1. Install WSL2:
-
-   ```powershell
-   wsl --install
-   ```
-
----
-
-## Initial setup
-
-Follow the instructions in [compiling from sources](compile.md).
-The steps assume the following environment:
-
-- Go installed at `/usr/local/go`
-- PHP source cloned to `~/php-src`
-- PHP built at: `/usr/local/bin/php`
-- FrankenPHP source cloned to `~/frankenphp`
-
-## CLion Setup for CGO glue/PHP Source Development
-
-### 1. Install CLion (on your host OS)
-
-- Download from: [https://www.jetbrains.com/clion/download/](https://www.jetbrains.com/clion/download/)
-
-- Launch (if on Windows, in WSL):
-
-  ```bash
-  clion &>/dev/null
-  ```
-
-### 2. Open Project in CLion
-
-- Open CLion → Open → Select the `~/frankenphp` directory
-- Add a build chain: Settings → Build, Execution, Deployment → Custom Build Targets
-- Select any Build Target, under `Build` set up an External Tool (call it e.g. go build)
-- Set up a wrapper script that builds frankenphp for you, called `go_compile_frankenphp.sh`
-
-```bash
-export CGO_CFLAGS="-O0 -g $(php-config --includes)"
-export CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)"
-go build -tags=nobadger,nomysql,nopgx
-```
-
-- Under Program, select `go_compile_frankenphp.sh`
-- Leave Arguments blank
-- Working Directory: `~/frankenphp/caddy/frankenphp`
-
-### 3. Configure Run Targets
-
-- Go to **Run → Edit Configurations**
-- Create:
-
-  - **frankenphp**:
-
-    - Type: Native Application
-    - Target: select the `go build` target you created
-    - Executable: `~/frankenphp/caddy/frankenphp/frankenphp`
-    - Arguments: the arguments you want to start frankenphp with, e.g. `php-cli test.php`
-
-### 4. Debug Go files from CLion
-
-- Right click on a *.go file in the Project view on the left
-- Override file type
-- C/C++
-
-Now you can place breakpoints in C, C++ and Go files.
-To get syntax highlighting for imports from php-src, you may need to tell CLion about the include paths. Create a
-`compile_flags.txt` file in `~/frankenphp` with the following contents:
-
-```gcc
--I/usr/local/include/php
--I/usr/local/include/php/Zend
--I/usr/local/include/php/main
--I/usr/local/include/php/TSRM
-```
-
----
-
-## GoLand Setup for FrankenPHP Development
-
-Use GoLand for primary Go development, but the debugger cannot debug C code.
-
-### 1. Install GoLand (on your host OS)
-
-- Download from: [https://www.jetbrains.com/go/download/](https://www.jetbrains.com/go/download/)
-
-- Launch (if on Windows, in WSL):
-
-  ```bash
-  goland &>/dev/null
-  ```
-
-### 2. Open in GoLand
-
-- Launch GoLand → Open → Select the `~/frankenphp` directory
-
----
-
-### Go Configuration
-
-- Select Go Build
-  - Name `frankenphp`
-  - Run kind: Directory
-
-- Directory: `~/frankenphp/caddy/frankenphp`
-- Output directory: `~/frankenphp/caddy/frankenphp`
-- Working directory: `~/frankenphp/caddy/frankenphp`
-- Environment (adjust for your $(php-config ...) output):
-  `CGO_CFLAGS=-O0 -g -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib;CGO_LDFLAGS=-lm -lpthread -lsqlite3 -lxml2 -lbrotlienc -lbrotlidec -lbrotlicommon -lwatcher`
-- Go tool arguments: `-tags=nobadger,nomysql,nopgx`
-- Program arguments: e.g. `php-cli -i`
-
-You can now place breakpoints and debug through Go code when you debug the `frankenphp` configuration, but breakpoints
-in C code will not work.
-
----
-
-## Debugging and Integration Notes
-
-- Use **CLion** for debugging PHP internals and `cgo` glue code
-- Use **GoLand** for primary Go development and debugging
-- FrankenPHP can be added as a run configuration in CLion for unified C/Go debugging if needed, but syntax highlighting
-  won't work in Go files
-
----

From 82dbba7a1fd3d526a10ec9b09add712e44d7ac6b Mon Sep 17 00:00:00 2001
From: henderkes <m@pyc.ac>
Date: Mon, 25 Aug 2025 18:37:02 +0700
Subject: [PATCH 10/10] no bare urls

---
 CONTRIBUTING.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 48775a3fb..d48c05386 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -211,7 +211,7 @@ The steps assume the following environment:
 
 1. Install CLion (on your host OS)
 
-   - Download from: https://www.jetbrains.com/clion/download/
+   - Download from [JetBrains](https://www.jetbrains.com/clion/download/)
    - Launch (if on Windows, in WSL):
 
      ```bash
@@ -269,7 +269,7 @@ Use GoLand for primary Go development, but the debugger cannot debug C code.
 
 1. Install GoLand (on your host OS)
 
-   - Download from: https://www.jetbrains.com/go/download/
+   - Download from [JetBrains](https://www.jetbrains.com/go/download/)
    - Launch (if on Windows, in WSL):
 
      ```bash