From 555e0526110eadb4ee7a3acb2ef152678a3fdec4 Mon Sep 17 00:00:00 2001 From: Petter Holmstrom Date: Fri, 30 May 2025 11:49:48 +0300 Subject: [PATCH 1/2] Explain how to install JBR manually --- articles/getting-started/run/vscode.adoc | 37 +++++++++++++++--------- 1 file changed, 23 insertions(+), 14 deletions(-) diff --git a/articles/getting-started/run/vscode.adoc b/articles/getting-started/run/vscode.adoc index 9f4dd6d39c..0c06581641 100644 --- a/articles/getting-started/run/vscode.adoc +++ b/articles/getting-started/run/vscode.adoc @@ -39,29 +39,38 @@ image::images/vscode-verified.png[Vaadin Copilot verifying that Java Hotswap is == Enabling Hotswap Manually -Enabling hotswap manually consists of three steps: +To manually enable hotswap support for a Vaadin application in Visual Studio Code, complete the following steps: -1. Download and install JetBrains Runtime; -2. Download HotswapAgent and install it into JetBrains Runtime; and -3. Create a launch configuration for VS Code that runs the application with JetBrain Runtime and additional JVM parameters. +1. Install JetBrains Runtime (JBR) +2. Install HotswapAgent into JBR +3. Configure VS Code to launch your application with JBR and HotswapAgent -=== JetBrains Runtime +=== Install JetBrains Runtime -You can download the latest version from the https://github.com/JetBrains/JetBrainsRuntime/releases[JetBrains GitHub release page]. Be sure to select the correct architecture. Use JetBrains Runtime to execute your application, not necessarily your IDE. +Download the latest _JetBrains Runtime with JCEF_ for your platform from the https://github.com/JetBrains/JetBrainsRuntime/releases[JetBrainsRuntime GitHub Releases] page. Choose a variant appropriate for your system (e.g., osx-aarch64, linux-x64, windows-x64): +* On macOS, use the `.pkg` installer, which installs JBR under: +`/Library/Java/JavaVirtualMachines/jbr_jcef-[version and platform]/Contents/Home` +* On Windows and Linux, download and extract the `.zip` or `.tar.gz` archive to a suitable location. -=== HotswapAgent +[NOTE] +The extracted directory contains a custom JVM with executables like `java` and `javac` inside the `bin/` folder. This is the JVM you'll use to run your application. -You can download HotswapAgent from the https://github.com/HotswapProjects/HotswapAgent/releases[HotswapAgent GitHub release page]. You'll need version 1.4.2 or later. +=== Install HotswapAgent -Download the JAR file and place it inside the JetBrains Runtime installation directory as [filename]`lib/hotswap/hotswap-agent.jar`. You'll need to create the `hotswap` folder, and rename the downloaded file to `hotswap-agent.jar`. +Download HotswapAgent (version 1.4.2 or later) from the https://github.com/HotswapProjects/HotswapAgent/releases[HotswapAgent GitHub Releases] page. Install it like this: -If you want to know more about the features of HotswapAgent, the documentation in the https://hotswapagent.org/[HotswapAgent webpage] is a good resource. +1. Create a subdirectory inside the JetBrains Runtime folder: `[JBR]/lib/hotswap/` +2. Rename the downloaded `.jar` file to `hotswap-agent.jar` and place it in that directory: `[JBR]/lib/hotswap/hotswap-agent.jar` + +.More info +[NOTE] +Visit https://hotswapagent.org/[hotswapagent.org] for details about supported features and integrations. === Launch Configuration -Inside your Java project, create a new `.vscode/launch.json` file with the following contents: +Create a `.vscode/launch.json` file in the root of your Java project with the following contents: [source,json] ---- @@ -80,8 +89,8 @@ Inside your Java project, create a new `.vscode/launch.json` file with the follo ] } ---- -<1> Replace with your main class. -<2> Replace with the name of your project. -<3> Replace with the path to your JetBrains Runtime installation. +<1> Replace with the fully-qualified name of your main class. +<2> Replace with your project's name. +<3> Replace with the path to your JetBrains Runtime `java` executable. With the launch configuration in place, you can now start the application from the *Run and Debug* tab in Visual Studio Code. Open the application in a browser and verify that everything is working through menu:Copilot[Development Workflow]. From c030ab45747ca5b0f9d598f05372ba5ee6143cc8 Mon Sep 17 00:00:00 2001 From: Petter Holmstrom Date: Mon, 2 Jun 2025 14:56:44 +0300 Subject: [PATCH 2/2] Move manual hotswap instructions to generic guide --- articles/getting-started/run/generic.adoc | 123 ++++++++++++++++++++++ articles/getting-started/run/vscode.adoc | 61 +---------- 2 files changed, 124 insertions(+), 60 deletions(-) create mode 100644 articles/getting-started/run/generic.adoc diff --git a/articles/getting-started/run/generic.adoc b/articles/getting-started/run/generic.adoc new file mode 100644 index 0000000000..e8aa834396 --- /dev/null +++ b/articles/getting-started/run/generic.adoc @@ -0,0 +1,123 @@ +--- +title: Generic +page-title: How to run a Vaadin application in any Java IDE +meta-description: Run your Vaadin application in any Java IDE and set up hotswap with JetBrains Runtime and HotswapAgent. +tab-title: Generic +order: 400 +--- + + += Generic +:toclevels: 2 + +You can run and debug your Vaadin application in any IDE or editor that supports Java. The `Application` class has a `main()` method, that you should run. The application starts up and you'll be able to access it at http://localhost:8080. Hot deploy of the frontend files is enabled automatically. However, to enable Java hotswap, you have to take some additional actions. + +== Enabling Hotswap Manually + +To manually enable hotswap support for a Vaadin application, complete the following steps: + +1. Install JetBrains Runtime (JBR) +2. Install HotswapAgent into JBR +3. Configure your IDE to launch your application with JBR and HotswapAgent + + +=== Install JetBrains Runtime + +Download the latest _JetBrains Runtime with JCEF_ for your platform from the https://github.com/JetBrains/JetBrainsRuntime/releases[JetBrainsRuntime GitHub Releases] page. Choose a variant appropriate for your system (e.g., osx-aarch64, linux-x64, windows-x64): + +* On macOS, use the `.pkg` installer, which installs JBR under: +`/Library/Java/JavaVirtualMachines/jbr_jcef-[version and platform]/Contents/Home` +* On Windows and Linux, download and extract the `.zip` or `.tar.gz` archive to a suitable location. + +[NOTE] +The extracted directory contains a custom JVM with executables like `java` and `javac` inside the `bin/` folder. This is the JVM you'll use to run your application. + + +=== Install HotswapAgent + +Download HotswapAgent (version 1.4.2 or later) from the https://github.com/HotswapProjects/HotswapAgent/releases[HotswapAgent GitHub Releases] page. Install it like this: + +1. Create a subdirectory inside the JetBrains Runtime folder: `[JBR]/lib/hotswap/` +2. Rename the downloaded `.jar` file to `hotswap-agent.jar` and place it in that directory: `[JBR]/lib/hotswap/hotswap-agent.jar` + +.More info +[NOTE] +Visit https://hotswapagent.org/[hotswapagent.org] for details about supported features and integrations. + + +=== Configure Application Launch with JetBrains Runtime and HotswapAgent + +To run your application with Hotswap support, launch it using the JetBrains Runtime and provide the required JVM arguments. Use the `java` executable from your installed JetBrains Runtime and add the necessary -XX options for class redefinition. + +.Example Command +[source,terminal] +---- +/path/to/jbr/bin/java \ + -XX:+AllowEnhancedClassRedefinition \ + -XX:+ClassUnloading \ + -XX:HotswapAgent=fatjar \ + -cp \ + com.example.application.Application +---- + +Replace: + +* `/path/to/jbr/bin/java` — with the full path to the java binary in your JetBrains Runtime installation. +* `` — with your application's full classpath (use : as a separator on macOS/Linux, ; on Windows). +* `com.example.application.Application` — with the fully-qualified name of your application's main class. + +[NOTE] +You may also set these VM arguments in your IDE's Run/Debug configuration, if it supports customizing the Java executable and arguments. + + +==== Enable Automatic Hotswap + +If your IDE does not notify the hotswap agent of recompiled classes, you have to enable it manually. Create a new file `src/main/resources/hotswap-agent.properties` and put the following in it: + +[source,properties] +---- +autoHotswap=true +---- + + +==== Compute the classpath + +If you use a build script to run build and run your application, you can use the following to automatically generate the classpath on Linux/macOS: + +[source,bash] +---- +CLASSPATH=$(mvn dependency:build-classpath -Dmdep.outputFile=/dev/stdout -q):target/classes +---- + +A complete build script on Linux/macOS could look like this: + +[source,bash] +---- +#!/bin/bash +JBR_PATH="/path/to/jbr" +MAIN_CLASS="com.example.Application" +CLASSPATH=$(mvn dependency:build-classpath -Dmdep.outputFile=/dev/stdout -q):target/classes + +$JBR_PATH/bin/java \ + -XX:+AllowEnhancedClassRedefinition \ + -XX:+ClassUnloading \ + -XX:HotswapAgent=fatjar \ + -cp "$CLASSPATH" \ + "$MAIN_CLASS" +---- + + +== Run and Verify Hotswap + +Once configured, run your application using the command or launch configuration you've set up. Then: + +1. Open the application in a browser. +2. Make a small change in your Java source code (e.g., update a label or log message). +3. Recompile the modified class (your editor or build tool *must support incremental compilation*). +4. HotswapAgent should automatically reload the updated class without restarting the application. + +Check your application's logs — you should see messages from HotswapAgent confirming the class was reloaded. If nothing happens, verify that: + +* The JVM used is JetBrains Runtime +* `hotswap-agent.jar` is correctly placed in `lib/hotswap/` +* All required JVM arguments are included diff --git a/articles/getting-started/run/vscode.adoc b/articles/getting-started/run/vscode.adoc index 0c06581641..cc876b6a13 100644 --- a/articles/getting-started/run/vscode.adoc +++ b/articles/getting-started/run/vscode.adoc @@ -1,7 +1,7 @@ --- title: Visual Studio Code page-title: How to run a Vaadin application in Visual Studio Code -meta-description: Run your Vaadin app in Visual Studio Code and enable Java hotswap with Vaadin Copilot or manual setup using JetBrains Runtime and HotswapAgent. +meta-description: Run your Vaadin app in Visual Studio Code and enable Java hotswap with Vaadin Copilot tab-title: VS Code order: 20 --- @@ -35,62 +35,3 @@ Copilot guides you through the steps needed to optimize your development workflo When you have completed all the steps, you can verify that everything is working. Start your application with hotswap enabled, and open it in a browser. Then select menu:Copilot[Development workflow] again. All the checkmarks should be green: image::images/vscode-verified.png[Vaadin Copilot verifying that Java Hotswap is enabled] - - -== Enabling Hotswap Manually - -To manually enable hotswap support for a Vaadin application in Visual Studio Code, complete the following steps: - -1. Install JetBrains Runtime (JBR) -2. Install HotswapAgent into JBR -3. Configure VS Code to launch your application with JBR and HotswapAgent - -=== Install JetBrains Runtime - -Download the latest _JetBrains Runtime with JCEF_ for your platform from the https://github.com/JetBrains/JetBrainsRuntime/releases[JetBrainsRuntime GitHub Releases] page. Choose a variant appropriate for your system (e.g., osx-aarch64, linux-x64, windows-x64): - -* On macOS, use the `.pkg` installer, which installs JBR under: -`/Library/Java/JavaVirtualMachines/jbr_jcef-[version and platform]/Contents/Home` -* On Windows and Linux, download and extract the `.zip` or `.tar.gz` archive to a suitable location. - -[NOTE] -The extracted directory contains a custom JVM with executables like `java` and `javac` inside the `bin/` folder. This is the JVM you'll use to run your application. - -=== Install HotswapAgent - -Download HotswapAgent (version 1.4.2 or later) from the https://github.com/HotswapProjects/HotswapAgent/releases[HotswapAgent GitHub Releases] page. Install it like this: - -1. Create a subdirectory inside the JetBrains Runtime folder: `[JBR]/lib/hotswap/` -2. Rename the downloaded `.jar` file to `hotswap-agent.jar` and place it in that directory: `[JBR]/lib/hotswap/hotswap-agent.jar` - -.More info -[NOTE] -Visit https://hotswapagent.org/[hotswapagent.org] for details about supported features and integrations. - - -=== Launch Configuration - -Create a `.vscode/launch.json` file in the root of your Java project with the following contents: - -[source,json] ----- -{ - "version": "0.2.0", - "configurations": [ - { - "type": "java", - "name": "Application", - "request": "launch", - "mainClass": "com.example.application.Application", // <1> - "projectName": "my-application", // <2> - "javaExec": "/path/to/jetbrains-runtime/bin/java", // <3> - "vmArgs": "-XX:+AllowEnhancedClassRedefinition -XX:+ClassUnloading -XX:HotswapAgent=fatjar" - } - ] -} ----- -<1> Replace with the fully-qualified name of your main class. -<2> Replace with your project's name. -<3> Replace with the path to your JetBrains Runtime `java` executable. - -With the launch configuration in place, you can now start the application from the *Run and Debug* tab in Visual Studio Code. Open the application in a browser and verify that everything is working through menu:Copilot[Development Workflow].