feat: add vscode/intellij debugger configs (#1918)

.dockerignore

@@ -3,6 +3,7 @@
 **/build
 **/.gradle
 **/.idea
+!**/.idea/runConfigurations/
 /.vscode
 !.vscode/tasks.json
 **/*.sw*

.gitignore

@@ -1,7 +1,9 @@
 .hermit/
-.vscode/
+.vscode/*
 !/.vscode/settings.json
-.idea/
+!/.vscode/launch.json
+.idea/*
+!.idea/runConfigurations/
 *.iml
 target/
 build/
@@ -20,6 +22,7 @@ testdata/**/go.work
 testdata/**/go.work.sum
 **/testdata/**/_ftl
 **/examples/**/_ftl
+**/examples/**/types.ftl.go
 buildengine/.gitignore
 go.work*
 junit*.xml

.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug FTL",
+            "type": "go",
+            "request": "attach",
+            "mode": "remote",
+            "apiVersion": 2,
+            "host": "127.0.0.1",
+            "port": 2345
+        }
+    ]
+}

CONTRIBUTING.md

@@ -150,6 +150,35 @@ just publish-extension
 
 This will publish the extension to the FTL marketplace. This command will require you to have a Personal Access Token (PAT) with the `Marketplace` scope. You can create a PAT [here](https://dev.azure.com/ftl-org/_usersSettings/tokens).
 
+## Debugging with Delve
+
+### Building with Full Debug Information
+
+To build a binary with full debug information for Delve, use the following command:
+
+```sh
+FTL_DEBUG=true just build ftl
+```
+
+### Debugging a Running Process
+
+For an in-line replacement of `ftl dev <args>`, use the command:
+
+```sh
+just debug <args>
+```
+
+This command compiles a binary with debug information, runs `ftl dev <args>` using this binary, and provides an endpoint to attach a remote debugger at __127.0.0.1:2345__.
+You do not need to run `FTL_DEBUG=true just build ftl` separately when using this command.
+### Attaching a Debugger
+
+By running `just debug <args>` and then attaching a remote debugger, you can debug the FTL infrastructure while running your project.
+
+#### IntelliJ
+Run `Debug FTL` from the `Run/Debug Configurations` dropdown while in the FTL project.
+#### VSCode
+Run `Debug FTL` from the `Run and Debug` dropdown while in the FTL project.
+
 ## Useful links
 
 - [VSCode extension samples](https://github.com/microsoft/vscode-extension-samples)

Justfile

@@ -50,7 +50,12 @@ build-generate:
 build +tools: build-protos build-zips build-frontend
   #!/bin/bash
   shopt -s extglob
-  for tool in $@; do mk "{{RELEASE}}/$tool" : !(build|integration) -- go build -o "{{RELEASE}}/$tool" -tags release -ldflags "-X github.com/TBD54566975/ftl.Version={{VERSION}} -X github.com/TBD54566975/ftl.Timestamp={{TIMESTAMP}}" "./cmd/$tool"; done
+
+  if [ "${FTL_DEBUG:-}" = "true" ]; then
+    for tool in $@; do go build -o "{{RELEASE}}/$tool" -tags release -gcflags=all="-N -l" -ldflags "-X github.com/TBD54566975/ftl.Version={{VERSION}} -X github.com/TBD54566975/ftl.Timestamp={{TIMESTAMP}}" "./cmd/$tool"; done
+  else
+    for tool in $@; do mk "{{RELEASE}}/$tool" : !(build|integration) -- go build -o "{{RELEASE}}/$tool" -tags release -ldflags "-X github.com/TBD54566975/ftl.Version={{VERSION}} -X github.com/TBD54566975/ftl.Timestamp={{TIMESTAMP}}" "./cmd/$tool"; done
+  fi
 
 # Build all backend binaries
 build-backend:
@@ -148,3 +153,20 @@ docs:
 # Generate LSP hover help text
 lsp-generate:
   @mk lsp/hoveritems.go : lsp docs/content -- "scripts/ftl-gen-lsp"
+
+# Run `ftl dev` providing a Delve endpoint for attaching a debugger.
+debug *args:
+  #!/bin/bash
+  set -euo pipefail
+
+  cleanup() {
+    if [ -n "${dlv_pid:-}" ] && kill -0 "$dlv_pid" 2>/dev/null; then
+      kill "$dlv_pid"
+    fi
+  }
+  trap cleanup EXIT
+
+  FTL_DEBUG=true just build ftl
+  dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec "{{RELEASE}}/ftl" -- dev {{args}} &
+  dlv_pid=$!
+  wait "$dlv_pid"

bin/.dlv-1.22.1.pkg

@@ -0,0 +1 @@
+hermit

bin/delve-1.22.1

@@ -0,0 +1 @@
+.dlv-1.22.1.pkg