Add IDE (GoLand/CLion) setup to CONTRIBUTING.md (#2269)

Signed-off-by: Marc <m@pyc.ac>
Co-authored-by: Kévin Dunglas <kevin@dunglas.fr>

Author: henderkes

.gitignore

@@ -13,3 +13,4 @@
 __debug_bin
 frankenphp.test
 *.log
+compile_flags.txt

CONTRIBUTING.md

@@ -249,6 +249,146 @@ docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 
 9. When the bug is fixed, revert all these changes
 
+## Development Environment Setup (WSL/Unix)
+
+### 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 [JetBrains](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
+   CGO_CFLAGS="-O0 -g" ./go.sh
+   ```
+
+   - 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 [JetBrains](https://www.jetbrains.com/go/download/)
+
+     ```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`
+
+To debug C files from GoLand
+
+- Right click on a *.c file in the Project view on the left
+- Override file type → Go
+
+Now you can place breakpoints in C, C++ and Go files.
+
+---
+
+### GoLand Setup on Windows
+
+1. Follow the [Windows Development section](#windows-development)
+
+2. Install GoLand
+
+   - Download from [JetBrains](https://www.jetbrains.com/go/download/)
+   - Launch GoLand
+
+3. Open in GoLand
+
+   - Select **Open** → Choose the directory where you cloned `frankenphp`
+
+4. Configure Go Build
+
+   - Go to **Run** → **Edit Configurations**
+   - Click **+** and select **Go Build**
+   - Name: `frankenphp`
+   - Run kind: **Directory**
+   - Directory: `.\caddy\frankenphp`
+   - Output directory: `.\caddy\frankenphp`
+   - Working directory: `.\caddy\frankenphp`
+   - Go tool arguments: `-tags=nobadger,nomysql,nopgx`
+   - Environment variables: see the [Windows Development section](#windows-development)
+   - Program arguments: e.g. `php-server`
+
+---
+
+### 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)