develop, run, debug in VSCode

.vscode/launch.json

@@ -0,0 +1,43 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "java",
+            "name": "Phoebus: Incremental Build and Debug",
+            "request": "launch",
+            "mainClass": "org.phoebus.product.Launcher",
+            "classPaths": [
+                "${workspaceFolder}/phoebus-product/target/*"
+            ],
+            "cwd": "${workspaceFolder}/phoebus-product/target",
+            "console": "integratedTerminal",
+            "preLaunchTask": "Build Phoebus product",
+            "args": []
+        },
+        {
+            "type": "java",
+            "name": "Phoebus: Debug Last Build (No Build)",
+            "request": "launch",
+            "mainClass": "org.phoebus.product.Launcher",
+            "classPaths": [
+                "${workspaceFolder}/phoebus-product/target/*"
+            ],
+            "cwd": "${workspaceFolder}/phoebus-product/target",
+            "console": "integratedTerminal",
+            "args": []
+        },
+        {
+            "type": "java",
+            "name": "Phoebus: Clean Build and Debug",
+            "request": "launch",
+            "mainClass": "org.phoebus.product.Launcher",
+            "classPaths": [
+                "${workspaceFolder}/phoebus-product/target/*"
+            ],
+            "cwd": "${workspaceFolder}/phoebus-product/target",
+            "console": "integratedTerminal",
+            "preLaunchTask": "Clean build Phoebus product",
+            "args": []
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "debug.hideSlowPreLaunchWarning": true,
+    "java.debug.settings.forceBuildBeforeLaunch": false,
+    "java.debug.settings.onBuildFailureProceed": false
+}

.vscode/tasks.json

@@ -0,0 +1,37 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build Phoebus product",
+            "type": "process",
+            "command": "mvn",
+            "args": [
+                "-DskipTests",
+                "install"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "problemMatcher": []
+        },
+        {
+            "label": "Clean build Phoebus product",
+            "type": "process",
+            "command": "mvn",
+            "args": [
+                "-DskipTests",
+                "clean",
+                "install"
+            ],
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "group": "build",
+            "problemMatcher": []
+        }
+    ]
+}

README.md

@@ -171,6 +171,29 @@ To run the Phoebus application:
    *Run* ➜ *Run Main Project* menu item.
 
 
+## Developing with VS Code
+
+Install [Visual Studio Code](https://code.visualstudio.com/) and the
+[Extension Pack for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack).
+Make sure a JDK 21 or later is installed and selected in VS Code (use
+**Java: Configure Java Runtime** from the Command Palette).
+
+Open the Phoebus root directory in VS Code. If the target platform has not yet
+been downloaded, run:
+
+```
+mvn clean verify -f dependencies/pom.xml
+```
+
+The workspace includes build tasks and launch configurations in `.vscode`.
+Select **Phoebus: Incremental Build and Debug** in the Run and Debug view and
+press the green play button. This builds the product with Maven, skipping unit
+tests, and launches `org.phoebus.product.Launcher`. Select
+**Phoebus: Clean Build and Debug** to clean before building, or
+**Phoebus: Debug Last Build (No Build)** to launch the most recent build
+without running a Maven build first.
+
+
 ## Complete Distribution, including manual and self-update
 
     # Obtain sources

phoebus-product/README.md

@@ -18,6 +18,48 @@ For site-specific examples, see
 
  * https://github.com/shroffk/nsls2-phoebus (actually creates several products for 'beamline' vs. 'accelerator')
  * https://github.com/kasemir/phoebus-sns
+
+## Running and debugging in VS Code
+
+Open the repository root in VS Code with the Java language support and Debugger
+for Java extensions installed. Maven must be on the terminal's `PATH`, and the
+Java extensions must use a JDK compatible with the root `pom.xml`.
+
+Select a configuration from `../.vscode/launch.json` in **Run and Debug**, then
+press **F5** to debug or **Ctrl+F5** to run without debugging:
+
+* **Phoebus: Incremental Build and Debug** runs the **Build Phoebus product**
+  task: `mvn -DskipTests install`, reusing existing build output where possible.
+* **Phoebus: Debug Last Build (No Build)** launches the existing packaged output
+  immediately. A successful build must already exist, and subsequent source
+  changes are not included until you build again.
+* **Phoebus: Clean Build and Debug** runs the **Clean build Phoebus product**
+  task: `mvn -DskipTests clean install`, rebuilding from scratch.
+
+Both build tasks are defined in `../.vscode/tasks.json` and run at the repository
+root. **Build Phoebus product** is also the default build task.
+
+The launch runs `org.phoebus.product.Launcher`, the product JAR's manifest entry
+point, with `phoebus-product/target` as its working directory. The classpath
+`phoebus-product/target/*` includes the product JAR; its manifest supplies the
+dependencies in `target/lib`, just as with `java -jar product-*-SNAPSHOT.jar`.
+This uses the packaged Maven output rather than the IDE's module classpath.
+
+The workspace setting `java.debug.settings.forceBuildBeforeLaunch` is disabled
+in `../.vscode/settings.json` to avoid a second, IDE-managed Java build after the
+Maven task. Maven is still required to succeed before launching; do not choose
+to debug anyway if the pre-launch Maven task fails.
+
+The workspace also enables `debug.hideSlowPreLaunchWarning` because the full
+Maven build normally takes longer than VS Code's ten-second notification delay.
+This hides the "Waiting for preLaunchTask" notification without bypassing the
+build or suppressing task failures.
+
+Set breakpoints in the Java sources before pressing F5. After source changes,
+restart with a build-and-debug configuration to rebuild the packaged JARs.
+Use a clean build after deleting or renaming sources if incremental output
+contains stale classes. Add application arguments,
+such as `"-nosplash"`, to the launch configuration's `args` array.
 
  ## Building native installers with `jpackage`