ci: build static binary with debug symbols

.github/workflows/static.yaml

@@ -69,11 +69,17 @@ jobs:
       matrix:
         platform: ${{ fromJson(needs.prepare.outputs.platforms) }}
         include:
-          - race: ""
+          -
             qemu: true
-          - platform: linux/amd64
+            debug: false
+          -
+            platform: linux/amd64
             qemu: false
-    name: Build ${{ matrix.platform }} static binary
+          -
+            platform: linux/amd64
+            qemu: false
+            debug: true
+    name: Build ${{ matrix.platform }} static binary${{ matrix.debug && ' (debug)' || '' }}
     runs-on: ubuntu-latest
     needs: [ prepare ]
     steps:
@@ -109,6 +115,7 @@ jobs:
           load: ${{ !fromJson(needs.prepare.outputs.push) }}
           targets: static-builder
           set: |
+            ${{ matrix.debug && 'static-builder.args.DEBUG_SYMBOLS=1' || '' }}
             *.tags=
             *.platform=${{ matrix.platform }}
             *.cache-from=type=gha,scope=${{ needs.prepare.outputs.ref || github.ref }}-static-builder
@@ -117,12 +124,12 @@ jobs:
             ${{ fromJson(needs.prepare.outputs.push) && format('*.output=type=image,name={0},push-by-digest=true,name-canonical=true,push=true', env.IMAGE_NAME) || '' }}
         env:
           SHA: ${{ github.sha }}
-          VERSION: ${{ (github.ref_type == 'tag' && github.ref_name) || needs.prepare.outputs.ref || github.sha}}
+          VERSION: ${{ (github.ref_type == 'tag' && github.ref_name) || needs.prepare.outputs.ref || github.sha }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       -
         # Workaround for https://github.com/actions/runner/pull/2477#issuecomment-1501003600
         name: Export metadata
-        if: fromJson(needs.prepare.outputs.push)
+        if: fromJson(needs.prepare.outputs.push) && !matrix.debug
         run: |
           mkdir -p /tmp/metadata
 
@@ -133,7 +140,7 @@ jobs:
           METADATA: ${{ steps.build.outputs.metadata }}
       -
         name: Upload metadata
-        if: fromJson(needs.prepare.outputs.push)
+        if: fromJson(needs.prepare.outputs.push) && !matrix.debug
         uses: actions/upload-artifact@v3
         with:
           name: metadata-static-builder
@@ -142,11 +149,11 @@ jobs:
           retention-days: 1
       -
         name: Copy binary
-        if: ${{ !fromJson(needs.prepare.outputs.push) }}
+        if: ${{ !fromJson(needs.prepare.outputs.push)  || matrix.debug }}
         run: |
           digest=$(jq -r '."static-builder"."containerimage.config.digest"' <<< "${METADATA}")
           docker create --platform=${{ matrix.platform }} --name static-builder "${digest}"
-          docker cp "static-builder:/go/src/app/dist/${BINARY}" "${BINARY}"
+          docker cp "static-builder:/go/src/app/dist/${BINARY}" "${BINARY}${{ matrix.debug && '-debug' || '' }}"
         env:
           METADATA: ${{ steps.build.outputs.metadata }}
           BINARY: frankenphp-linux-${{ matrix.platform == 'linux/amd64' && 'x86_64' || 'aarch64' }}
@@ -155,8 +162,8 @@ jobs:
         if: ${{ !fromJson(needs.prepare.outputs.push) }}
         uses: actions/upload-artifact@v3
         with:
-          name: frankenphp-linux-${{ matrix.platform == 'linux/amd64' && 'x86_64' || 'aarch64' }}
-          path: frankenphp-linux-${{ matrix.platform == 'linux/amd64' && 'x86_64' || 'aarch64' }}
+          name: frankenphp-linux-${{ matrix.platform == 'linux/amd64' && 'x86_64' || 'aarch64' }}${{ matrix.debug && '-debug' || '' }}
+          path: frankenphp-linux-${{ matrix.platform == 'linux/amd64' && 'x86_64' || 'aarch64' }}${{ matrix.debug && '-debug' || '' }}
   # Adapted from https://docs.docker.com/build/ci/github-actions/multi-platform/
   push:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -105,6 +105,32 @@ Build FrankenPHP images from scratch for arm64 & amd64 and push to Docker Hub:
 docker buildx bake -f docker-bake.hcl --pull --no-cache --push
 ```
 
+## Debugging Segmentation Faults With Static Builds
+
+1. Download the debug version of the FrankenPHP binary from GitHub or create your custom static build inlcuidng debug symbols:
+
+    ```console
+    docker buildx bake \
+        --load \
+        --set static-builder.args.DEBUG_SYMBOLS=1 \
+        --set "static-builder.platform=linux/amd64" \
+        static-builder
+    docker cp $(docker create --name static-builder dunglas/frankenphp:static-builder):/go/src/app/dist/frankenphp-linux-$(uname -m) frankenphp
+    ```
+
+2. Replace your current version of `frankenphp` by 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:
+
+    ```console
+    gdb -p `pidof frankenphp`
+    ```
+
+5. If necessary, type `continue` in the GDB shell
+6. Make FrankenPHP crash
+7. Type `bt` in the GDB shell
+8. Copy the output
+
 ## Debugging Segmentation Faults in GitHub Actions
 
 1. Open `.github/workflows/tests.yml`

build-static.sh

@@ -145,9 +145,9 @@ if [ -d "${EMBED}" ]; then
     truncate -s 0 app_checksum.txt
 fi
 
-if type "upx" > /dev/null; then
+if type "upx" > /dev/null && [ -z "${DEBUG_SYMBOLS}" ]; then
     upx --best "dist/${bin}"
-fi 
+fi
 
 "dist/${bin}" version
 

static-builder.Dockerfile

@@ -2,19 +2,13 @@
 FROM golang-base
 
 ARG FRANKENPHP_VERSION=''
-ENV FRANKENPHP_VERSION=${FRANKENPHP_VERSION}
-
 ARG PHP_VERSION=''
-ENV PHP_VERSION=${PHP_VERSION}
-
 ARG PHP_EXTENSIONS=''
-ENV PHP_EXTENSIONS=${PHP_EXTENSIONS}
-
 ARG PHP_EXTENSION_LIBS=''
-ENV PHP_EXTENSION_LIBS=${PHP_EXTENSION_LIBS}
-
 ARG CLEAN=''
 ARG EMBED=''
+ARG DEBUG_SYMBOLS=''
+
 SHELL ["/bin/ash", "-eo", "pipefail", "-c"]
 
 LABEL org.opencontainers.image.title=FrankenPHP