Karl-Erik Enkelmann created
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/Adocs/src/debugger.md | 1
docs/src/languages/java.md | 235 +++++++++++++++++++--------------------
2 files changed, 118 insertions(+), 118 deletions(-)
@@ -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)
@@ -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)