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 9f4dd6d39c..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,53 +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 - -Enabling hotswap manually consists of three 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. - -=== 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. - - -=== HotswapAgent - -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. - -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`. - -If you want to know more about the features of HotswapAgent, the documentation in the https://hotswapagent.org/[HotswapAgent webpage] is a good resource. - - -=== Launch Configuration - -Inside your Java project, create a new `.vscode/launch.json` file 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 your main class. -<2> Replace with the name of your project. -<3> Replace with the path to your JetBrains Runtime installation. - -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].