From 17933f12229d3f33cf62103f6e832bc84aef09e8 Mon Sep 17 00:00:00 2001 From: Karl-Erik Enkelmann <110300169+playdohface@users.noreply.github.com> Date: Wed, 5 Nov 2025 12:24:29 +0100 Subject: [PATCH] Update documentation on Java support (#41758) This brings the documentation on Java in line with the much changed reality of the Java extension. Note that the correctness of this is contingent on https://github.com/zed-industries/extensions/pull/3745 being merged. Release Notes: - N/A --- docs/src/debugger.md | 1 + docs/src/languages/java.md | 235 ++++++++++++++++++------------------- 2 files changed, 118 insertions(+), 118 deletions(-) diff --git a/docs/src/debugger.md b/docs/src/debugger.md index 4c13f1f8e8004c4eb18af518f458e34421a7aac5..15094be360bbe5d454e032573f4dc75464271b3f 100644 --- a/docs/src/debugger.md +++ b/docs/src/debugger.md @@ -17,6 +17,7 @@ To debug code written in a specific language, Zed needs to find a debug adapter - [C](./languages/c.md#debugging) (built-in) - [C++](./languages/cpp.md#debugging) (built-in) - [Go](./languages/go.md#debugging) (built-in) +- [Java](./languages/java.md#debugging) (provided by extension) - [JavaScript](./languages/javascript.md#debugging) (built-in) - [PHP](./languages/php.md#debugging) (built-in) - [Python](./languages/python.md#debugging) (built-in) diff --git a/docs/src/languages/java.md b/docs/src/languages/java.md index 966f2352b3955e9ed2574eab34a717dc14832d3d..482429aef30e1a5d21e9277a31a6e78f0905be8c 100644 --- a/docs/src/languages/java.md +++ b/docs/src/languages/java.md @@ -19,150 +19,149 @@ Or manually download and install [OpenJDK 23](https://jdk.java.net/23/). ## Extension Install -You can install either by opening {#action zed::Extensions}({#kb zed::Extensions}) and searching for `java`. +You can install by opening {#action zed::Extensions}({#kb zed::Extensions}) and searching for `java`. -## Settings / Initialization Options +## Quick start and configuration -The extension will automatically download the language server, see: [Manual JDTLS Install](#manual-jdts-install) below if you'd prefer to manage that yourself. +For the majority of users, Java support should work out of the box. -For available `initialization_options` please see the [Initialize Request section of the Eclipse.jdt.ls Wiki](https://github.com/eclipse-jdtls/eclipse.jdt.ls/wiki/Running-the-JAVA-LS-server-from-the-command-line#initialize-request). +- It is generally recommended to open projects with the Zed-project root at the Java project root folder (where you would commonly have your `pom.xml` or `build.gradle` file). -You can add these customizations to your Zed Settings by launching {#action zed::OpenSettings}({#kb zed::OpenSettings}) or by using a `.zed/setting.json` inside your project. +- By default the extension will download and run the latest official version of JDTLS for you, but this requires Java version 21 to be available on your system via either the `$JAVA_HOME` environment variable or as a `java(.exe)` executable on your `$PATH`. If your project requires a lower Java version in the environment, you can specify a different JDK to use for running JDTLS via the `java_home` configuration option. -### Zed Java Settings +- You can provide a **custom launch script for JDTLS**, by adding an executable named `jdtls` (or `jdtls.bat` on Windows) to your `$PATH` environment variable. If this is present, the extension will skip downloading and launching a managed instance and use the one from the environment. -```json [settings] +- To support [Lombok](https://projectlombok.org/), the lombok-jar must be downloaded and registered as a Java-Agent when launching JDTLS. By default the extension automatically takes care of that, but in case you don't want that you can set the `lombok_support` configuration-option to `false`. + +Here is a common `settings.json` including the above mentioned configurations: + +```jsonc { "lsp": { "jdtls": { - "initialization_options": {} - } - } + "settings": { + "java_home": "/path/to/your/JDK21+", + "lombok_support": true, + }, + }, + }, } ``` -## Example Configs +## Debugging + +Debug support is enabled via our [Fork of Java Debug](https://github.com/zed-industries/java-debug), which the extension will automatically download and start for you. Please refer to the [Debugger Documentation](https://zed.dev/docs/debugger#getting-started) for general information about how debugging works in Zed. + +To get started with Java, click the `edit debug.json` button in the Debug menu, and replace the contents of the file with the following: + +```jsonc +[ + { + "adapter": "Java", + "request": "launch", + "label": "Launch Debugger", + // if your project has multiple entry points, specify the one to use: + // "mainClass": "com.myorganization.myproject.MyMainClass", + // + // this effectively sets a breakpoint at your program entry: + "stopOnEntry": true, + // the working directory for the debug process + "cwd": "$ZED_WORKTREE_ROOT", + }, +] +``` -### JDTLS Binary +You should then be able to start a new Debug Session with the "Launch Debugger" scenario from the debug menu. -By default, zed will look in your `PATH` for a `jdtls` binary, if you wish to specify an explicit binary you can do so via settings: +## Launch Scripts (aka Tasks) in Windows -```json [settings] - "lsp": { - "jdtls": { - "binary": { - "path": "/path/to/java/bin/jdtls", - // "arguments": [], - // "env": {}, - "ignore_system_version": true - } - } - } -``` +This extension provides tasks for running your application and tests from within Zed via little play buttons next to tests/entry points. However, due to current limitations of Zed's extension interface, we can not provide scripts that will work across Maven and Gradle on both Windows and Unix-compatible systems, so out of the box the launch scripts only work on Mac and Linux. -### Zed Java Initialization Options +There is a fairly straightforward fix that you can apply to make it work on Windows by supplying your own task scripts. Please see [this Issue](https://github.com/zed-extensions/java/issues/94) for information on how to do that and read the [Tasks section in Zeds documentation](https://zed.dev/docs/tasks) for more information. -There are also many more options you can pass directly to the language server, for example: +## Advanced Configuration/JDTLS initialization Options -```json [settings] +JDTLS provides many configuration options that can be passed via the `initialize` LSP-request. The extension will pass the JSON-object from `lsp.jdtls.settings.initialization_options` in your settings on to JDTLS. Please refer to the [JDTLS Configuration Wiki Page](https://github.com/eclipse-jdtls/eclipse.jdt.ls/wiki/Running-the-JAVA-LS-server-from-the-command-line#initialize-request) for the available options and values. Below is an example `settings.json` that would pass on the example configuration from the above wiki page to JDTLS: + +```jsonc { "lsp": { "jdtls": { - "initialization_options": { - "bundles": [], - "workspaceFolders": ["file:///home/snjeza/Project"], - "settings": { - "java": { - "home": "/usr/local/jdk-9.0.1", - "errors": { - "incompleteClasspath": { - "severity": "warning" - } - }, - "configuration": { - "updateBuildConfiguration": "interactive", - "maven": { - "userSettings": null - } - }, - "trace": { - "server": "verbose" - }, - "import": { - "gradle": { - "enabled": true + "settings": { + // this will be sent to JDTLS as initializationOptions: + "initialization_options": { + "bundles": [], + // use this if your zed project root folder is not the same as the java project root: + "workspaceFolders": ["file:///home/snjeza/Project"], + "settings": { + "java": { + "home": "/usr/local/jdk-9.0.1", + "errors": { + "incompleteClasspath": { + "severity": "warning", + }, }, - "maven": { - "enabled": true + "configuration": { + "updateBuildConfiguration": "interactive", + "maven": { + "userSettings": null, + }, + }, + "import": { + "gradle": { + "enabled": true, + }, + "maven": { + "enabled": true, + }, + "exclusions": [ + "**/node_modules/**", + "**/.metadata/**", + "**/archetype-resources/**", + "**/META-INF/maven/**", + "/**/test/**", + ], + }, + "referencesCodeLens": { + "enabled": false, + }, + "signatureHelp": { + "enabled": false, + }, + "implementationCodeLens": "all", + "format": { + "enabled": true, + }, + "saveActions": { + "organizeImports": false, + }, + "contentProvider": { + "preferred": null, + }, + "autobuild": { + "enabled": false, + }, + "completion": { + "favoriteStaticMembers": [ + "org.junit.Assert.*", + "org.junit.Assume.*", + "org.junit.jupiter.api.Assertions.*", + "org.junit.jupiter.api.Assumptions.*", + "org.junit.jupiter.api.DynamicContainer.*", + "org.junit.jupiter.api.DynamicTest.*", + ], + "importOrder": ["java", "javax", "com", "org"], }, - "exclusions": [ - "**/node_modules/**", - "**/.metadata/**", - "**/archetype-resources/**", - "**/META-INF/maven/**", - "/**/test/**" - ] - }, - "jdt": { - "ls": { - "lombokSupport": { - "enabled": false // Set this to true to enable lombok support - } - } - }, - "referencesCodeLens": { - "enabled": false - }, - "signatureHelp": { - "enabled": false - }, - "implementationsCodeLens": { - "enabled": false - }, - "format": { - "enabled": true - }, - "saveActions": { - "organizeImports": false - }, - "contentProvider": { - "preferred": null - }, - "autobuild": { - "enabled": false }, - "completion": { - "favoriteStaticMembers": [ - "org.junit.Assert.*", - "org.junit.Assume.*", - "org.junit.jupiter.api.Assertions.*", - "org.junit.jupiter.api.Assumptions.*", - "org.junit.jupiter.api.DynamicContainer.*", - "org.junit.jupiter.api.DynamicTest.*" - ], - "importOrder": ["java", "javax", "com", "org"] - } - } - } - } - } - } + }, + }, + }, + }, + }, } ``` -## Manual JDTLS Install - -If you prefer, you can install JDTLS yourself and the extension can be configured to use that instead. - -- macOS: `brew install jdtls` -- Arch: [`jdtls` from AUR](https://aur.archlinux.org/packages/jdtls) - -Or manually download install: - -- [JDTLS Milestone Builds](http://download.eclipse.org/jdtls/milestones/) (updated every two weeks) -- [JDTLS Snapshot Builds](https://download.eclipse.org/jdtls/snapshots/) (frequent updates) - ## See also -- [Zed Java Repo](https://github.com/zed-extensions/java) -- [Zed Java Issues](https://github.com/zed-extensions/java/issues) +[Zed Java Repo](https://github.com/zed-extensions/java) +[Eclipse JDTLS Repo](https://github.com/eclipse-jdtls/eclipse.jdt.ls)