diff --git a/README.md b/README.md index d66b22b..e07f0c1 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,24 @@ # Java Extension for Zed -This extension adds support for the Java language to [Zed](https://zed.dev). It is using the [Eclipse JDT Language Server](https://projects.eclipse.org/projects/eclipse.jdt.ls) (JDTLS for short) to provide completions, code-actions and diagnostics. +This extension adds support for Java and `.properties` files to [Zed](https://zed.dev). It uses the [Eclipse JDT Language Server](https://projects.eclipse.org/projects/eclipse.jdt.ls) (JDTLS for short) to provide completions, code-actions and diagnostics. ## Quick Start Install the extension via Zeds extension manager. It should work out of the box for most people. However, there are some things to know: -- 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). The extension will automatically detect Maven and Gradle projects in subdirectories, but opening at the project root provides the best experience. +- 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). The extension will automatically detect Maven and Gradle projects in subdirectories, but opening at the project root provides the best experience. If you're working with a non-standard project layout or encounter issues with classpath resolution, see [Advanced Configuration/JDTLS initialization Options](#advanced-configurationjdtls-initialization-options) for fine-tuning. -- 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. +- By default the extension will download and run the latest official version of JDTLS for you, but this requires Java version 21 or higher to be available on your system via either the `$JAVA_HOME` environment variable or as a `java(.exe)` executable on your `$PATH`. The `java_home` configuration option allows you to specify a **separate** JDK 21+ installation specifically for running JDTLS — this is useful when your system default Java is a lower version required by your project. Note that `java_home` is also passed as the `JAVA_HOME` environment variable to the JDTLS process; to configure runtimes for your project itself, use `initialization_options.settings.java.configuration.runtimes` (see [Configuring Project Runtimes](#configuring-project-runtimes) below). -- 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. +- You can provide a **custom JDTLS binary** through one of these mechanisms (in priority order): + 1. The `jdtls_launcher` setting — specify an absolute path to a JDTLS launch script + 2. An executable named `jdtls` (or `jdtls.bat` on Windows) on your `$PATH` + + When either is found, the extension will skip downloading and launching a managed JDTLS instance and use the provided one instead. - 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`. -- The option to let the extension automatically download a version of OpenJDK can be enabled by setting `jdk_auto_download` to `true`. When enabled, the extension will only download a JDK if no valid java_home is provided or if the specified one does not meet the minimum version requirement. User-provided JDKs **always** take precedence. +- The option to let the extension automatically download a JDK can be enabled by setting `jdk_auto_download` to `true`. When enabled, the extension will download [Amazon Corretto](https://aws.amazon.com/corretto/) (an OpenJDK distribution) if no valid `java_home` is provided or if the specified one does not meet the minimum version requirement (Java 21). User-provided JDKs **always** take precedence. Here is a common `settings.json` including the above mentioned configurations: @@ -22,10 +26,17 @@ Here is a common `settings.json` including the above mentioned configurations: "lsp": { "jdtls": { "settings": { + // Path to a JDK 21+ used to run JDTLS. + // Also accepts the legacy key "java.home". "java_home": "/path/to/your/JDK21+", "lombok_support": true, "jdk_auto_download": false, + // JVM heap size for JDTLS (maps to -Xms and -Xmx) + // Accepts values like "512m", "1G", "4096m", etc. + "min_memory": "1G", // default: "1G" + "max_memory": "2G", // default: unset (no -Xmx limit) + // Controls when to check for updates for JDTLS, Lombok, and Debugger // - "always" (default): Always check for and download the latest version // - "once": Check for updates only if no local installation exists @@ -55,6 +66,8 @@ JDTLS uses **CamelCase fuzzy matching** for symbol queries. For example, searchi 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 [Zed Documentation](https://zed.dev/docs/debugger#getting-started) for general information about how debugging works in Zed. +### Launch Mode + 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 [ @@ -75,6 +88,55 @@ To get started with Java, click the `edit debug.json` button in the Debug menu, You should then be able to start a new Debug Session with the "Launch Debugger" scenario from the debug menu. +### Attach Mode + +You can attach to a running JVM process that was started with debug options (e.g. `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005`): + +```jsonc +[ + { + "label": "Attach to JVM (port 5005)", + "adapter": "Java", + "request": "attach", + "hostName": "localhost", + "port": 5005 + } +] +``` + +### Debug Configuration Reference + +The following options are available in `debug.json` for **launch** configurations: + +| Option | Type | Description | +|--------|------|-------------| +| `request` | `"launch"` | Required. The request type. | +| `mainClass` | `string` | Fully qualified class name. Auto-resolved if omitted. | +| `projectName` | `string` | Project name to disambiguate when multiple projects exist. | +| `args` | `string \| string[]` | Command line arguments passed to the program. | +| `vmArgs` | `string \| string[]` | Extra JVM options (e.g. `-Xmx2G -Dprop=value`). | +| `classPaths` | `string[]` | Classpaths for the JVM. Special values: `$Auto`, `$Runtime`, `$Test`. | +| `modulePaths` | `string[]` | Module paths for the JVM. Auto-resolved if omitted. | +| `cwd` | `string` | Working directory. Defaults to the worktree root. | +| `env` | `object` | Extra environment variables for the program. | +| `encoding` | `string` | The `file.encoding` setting for the JVM. | +| `stopOnEntry` | `boolean` | Pause the program after launching. | +| `noDebug` | `boolean` | Launch without attaching the debugger (e.g. for profiling). | +| `console` | `string` | Console type: `internalConsole`, `integratedTerminal`, or `externalTerminal`. | +| `shortenCommandLine` | `string` | Shorten long command lines: `none`, `jarmanifest`, or `argfile`. | +| `launcherScript` | `string` | Path to a custom JVM launcher script. | +| `javaExec` | `string` | Path to a specific Java executable. | + +For **attach** configurations: + +| Option | Type | Description | +|--------|------|-------------| +| `request` | `"attach"` | Required. The request type. | +| `hostName` | `string` | Host name or IP of the remote debuggee. | +| `port` | `integer` | Debug port of the remote debuggee. | +| `timeout` | `integer` | Timeout before reconnecting in milliseconds (default: 30000). | +| `projectName` | `string` | Project name for source resolution. | + ### Single-File Debugging If you're working a lot with single file debugging, you can use the following `debug.json` config instead: @@ -107,8 +169,68 @@ This extension provides tasks for running your application and tests from within 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. +## Configuring Project Runtimes + +If your project targets a Java version different from the one running JDTLS, you can register multiple JDK installations via `java.configuration.runtimes`. JDTLS will use these to compile and run your project at the correct language level, while still running itself on JDK 21+. + +```jsonc +"lsp": { + "jdtls": { + "settings": { + // JDK 21+ for running JDTLS itself + "java_home": "/usr/lib/jvm/java-21-openjdk" + }, + "initialization_options": { + "settings": { + "java": { + "configuration": { + "runtimes": [ + { + "name": "JavaSE-1.8", + "path": "/usr/lib/jvm/java-8-openjdk" + }, + { + "name": "JavaSE-11", + "path": "/usr/lib/jvm/java-11-openjdk" + }, + { + "name": "JavaSE-17", + "path": "/usr/lib/jvm/java-17-openjdk" + }, + { + "name": "JavaSE-21", + "path": "/usr/lib/jvm/java-21-openjdk", + "default": true + } + ] + } + } + } + } + } +} +``` + +- `name` must match an [execution environment identifier](https://wiki.eclipse.org/Execution_Environments) (e.g. `JavaSE-1.8`, `JavaSE-11`, `JavaSE-17`, `JavaSE-21`). Note that Java 8 uses the `1.8` naming convention while Java 9+ uses the major version number directly. +- `path` is the absolute path to the JDK installation root (the directory containing `bin/java`). +- `default` (optional) — set to `true` on the runtime JDTLS should use when no project-specific source level is detected. + +JDTLS will automatically pick the appropriate runtime based on your project's source level (from `pom.xml`, `build.gradle`, or `.classpath`). For example, a Maven project with `11` will use the `JavaSE-11` runtime for compilation and code analysis. + +> **macOS paths** typically look like `/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home` +> +> **Windows paths** typically look like `C:\Program Files\Java\jdk-17` + ## 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.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 opinionated example configuration for JDTLS with most options enabled: + +JDTLS provides many configuration options that can be passed via the `initialize` LSP-request. The extension will pass the JSON-object from `lsp.jdtls.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. + +The extension automatically injects the following defaults into `initialization_options` (unless you override them): +- `workspaceFolders` — set to the worktree root as a `file://` URI +- `extendedClientCapabilities.classFileContentsSupport` — `true` (enables decompiled source navigation) +- `extendedClientCapabilities.resolveAdditionalTextEditsSupport` — `true` + +Below is an opinionated example configuration for JDTLS with most options enabled: ```jsonc "lsp": { @@ -265,4 +387,8 @@ MyProject/ } ``` -If changes are not picked up, clean JDTLS' cache (from a java file run the task `Clear JDTLS cache`) and restart the language server +If changes are not picked up, clean JDTLS' cache (from a java file run the task `Clear JDTLS cache`) and restart the language server. + +## Architecture Note + +The extension uses a native binary (`java-lsp-proxy`) that wraps the JDTLS process. This proxy enables the extension to communicate with JDTLS for features like debug class resolution and classpath queries. It is automatically downloaded from the [extension repository releases](https://github.com/zed-extensions/java/releases) and requires no user configuration.