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
This commit is contained in:
Karl-Erik Enkelmann
+116
-117
@@ -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
|
||||
|
||||
### JDTLS Binary
|
||||
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.
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```json [settings]
|
||||
"lsp": {
|
||||
"jdtls": {
|
||||
"binary": {
|
||||
"path": "/path/to/java/bin/jdtls",
|
||||
// "arguments": [],
|
||||
// "env": {},
|
||||
"ignore_system_version": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```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",
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
### Zed Java Initialization Options
|
||||
You should then be able to start a new Debug Session with the "Launch Debugger" scenario from the debug menu.
|
||||
|
||||
There are also many more options you can pass directly to the language server, for example:
|
||||
## Launch Scripts (aka Tasks) in Windows
|
||||
|
||||
```json [settings]
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Advanced Configuration/JDTLS initialization Options
|
||||
|
||||
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)
|
||||
|
||||
Reference in New Issue
Block a user