From b6fd35863bd6dfc4182bbbe17fba7db4667d7ee0 Mon Sep 17 00:00:00 2001 From: Seth Nemesure Date: Tue, 13 Oct 2026 14:55:34 -0400 Subject: [PATCH] develop, run, debug in VSCode --- .vscode/launch.json | 43 +++++++++++++++++++++++++++++++++++++++ .vscode/settings.json | 5 +++++ .vscode/tasks.json | 37 +++++++++++++++++++++++++++++++++ README.md | 23 +++++++++++++++++++++ phoebus-product/README.md | 42 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 150 insertions(+) create mode 100644 .vscode/launch.json create mode 100644 .vscode/settings.json create mode 100644 .vscode/tasks.json diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000000..aa890fedfd --- /dev/null +++ b/.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": [] + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000..5807391434 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "debug.hideSlowPreLaunchWarning": true, + "java.debug.settings.forceBuildBeforeLaunch": false, + "java.debug.settings.onBuildFailureProceed": false +} \ No newline at end of file diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000000..65cc427a8c --- /dev/null +++ b/.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": [] + } + ] +} diff --git a/README.md b/README.md index 34a4349184..4d758da888 100644 --- a/README.md +++ b/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 diff --git a/phoebus-product/README.md b/phoebus-product/README.md index 96fb1a4d96..b09513e42f 100644 --- a/phoebus-product/README.md +++ b/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`