diff --git a/docs/Extensions.md b/docs/Extensions.md index ccf4e714..2167d741 100644 --- a/docs/Extensions.md +++ b/docs/Extensions.md @@ -12,31 +12,133 @@ To do that: * register your custom completion participant in the XML extension like [MavenCompletionParticipant](https://github.com/eclipse/lemminx-maven/blob/master/lemminx-maven/src/main/java/org/eclipse/lemminx/extensions/maven/MavenCompletionParticipant.java#L75) * register your custom XML extension with [Java Service Provider Interface (SPI)](https://www.baeldung.com/java-spi) mechanism in the [/META-INF/services/org.eclipse.lemminx.services.extensions.IXMLExtension](https://github.com/eclipse/lemminx-maven/blob/master/lemminx-maven/src/main/resources/META-INF/services/org.eclipse.lemminx.services.extensions.IXMLExtension) file. * build a JAR `your-custom-xml-extension.jar`. - * create a `vscode extension` which embeds the `your-custom-xml-extension.jar` JAR and declares this JAR path in the `package.json`: - -```json -"contributes": { - "xml.javaExtensions": [ - "./jar/your-custom-xml-extension.jar" - ] -} -``` - - * You can also list multiple jars or use glob patterns to specify the jars: - -```json -"contributes": { - "xml.javaExtensions": [ - "./jar/dependencies/*.jar", - "./jar/my-xml-extension.jar" - ] -} -``` + * refer to [Running your Java LemMinX extension](#Running-your-Java-LemMinX-extension) for instructions on setting up the Java LemMinX extension to run in VS Code You can see the [vscode-xml-maven](https://github.com/angelozerr/vscode-xml-maven) sample which registers custom maven completion [MavenCompletionParticipant](https://github.com/eclipse/lemminx-maven/blob/master/lemminx-maven/src/main/java/org/eclipse/lemminx/extensions/maven/MavenCompletionParticipant.java#L210) for scope: ![demo of vscode xml maven suggesting different scopes for a dependency](./images/vscode-xml-maven.gif) +### Running your Java LemMinX extension + +In order to run your Java LemMinX extension, you need to compile it and register with the vscode-xml VS Code extension. + +The first step in this process is compiling your Java LemMinX extension into the `.jar` format. +You can use either an Uber `.jar` (one `.jar` with all the dependencies bundled) or a group of `.jar`s (one `.jar` for your extension and one `.jar` for each dependency). +Once you have your `.jar`(s), you must register them with vscode-xml in one of two ways: + +1. **Register with a new VS Code TypeScript/JavaScript extension**: + + Make a new VS Code TypeScript/JavaScript extension using the instructions in the [VS Code extension development documentation](https://code.visualstudio.com/api/get-started/your-first-extension). + Embed the `.jar`(s) into the VS Code TypeScript/JavaScript extension by copying them into the same folder as the `package.json`, or a child folder. + In the `package.json`, add the `"xml.javaExtensions"` section under the `"contributes"` section, and list the paths to all of the `.jar`s of your Java LemMinX extension. + You can also use glob patterns to simplify this: + + ```json + "contributes": { + "xml.javaExtensions": [ + "./jar/dependencies/*.jar", + "./jar/my-xml-extension.jar" + ] + } + ``` + + Open the debug sidebar (Ctrl+Shift+D), and select "Launch extension". + This will run your VS Code TypeScript/JavaScript extension in a new instance of VS Code. + Your Java LemMinX extension will be running in this instance of VS Code. + Every time you make changes to your Java LemMinX extension, you will need to compile it into `.jar`s, copy the `.jar`s over to your VS Code TypeScript/JavaScript extension folder, and restart the debug version of VS Code. + +2. **Register the `.jar`(s) using the `"xml.extension.jars"` setting:** + + This method is intended only for development and debugging purposes, and should not be used to distribute your Java LemMinX extension. + Add the following entry to your VS Code `settings.json`: + + ```json + "xml.extension.jars": [ + "/absolute/path/to/your/JavaLemMinXExtension.jar" + ], + ``` + + Make sure to list all the `.jar`s that are needed to run your extension. + All the paths must be absolute paths (see [#383](https://github.com/redhat-developer/vscode-xml/issues/383)). + You can use glob patterns to specify groups of `.jar`s. + If you add, remove, or modify an entry in this list, the change won't take affect in the current VS Code window until you close and reopen that VS Code window. + In order for changes to your Java LemMinX extension to be reflected in VS Code, you must recompile the `.jar`(s), then close and reopen the VS Code window. + +### Debugging your Java LemMinX extension + +In order to debug your Java LemMinX extension, your Java LemMinX extension needs to be running. +Please make sure to read [Running your Java LemMinX extension](#Running-your-Java-LemMinX-extension) first. + +You can debug your Java LemMinX extension in any Java IDE that supports remote debugging. Here are the debugging instructions for both VS Code (with vscode-java) and Eclipse. + +#### VS Code + +1. Create a file `.vscode/launch.json` in your Java LemMinX extension project folder. + The folder structure should look something like this: + + ``` + | v .vscode + | | - launch.json + | v src + | | > main + | | > test + | > target + | - pom.xml + | - mvnw + | ... + ``` + +2. In `launch.json`, add the following, Change the value of `projectName` to the name of your extension: + ```json + { + "version": "0.2.0", + "configurations": [{ + "type": "java", + "name": "Remote Debug Java LemMinX extension", + "request": "attach", + "hostName": "localhost", + "port": 1054, + "projectName": "your.lemminx.extension.name" + }] + } + ``` +3. Open two VS Code windows: + * One that runs vscode-xml with your Java LemMinX extension + * One that has your Java LemMinX extension project folder open. i.e. open the folder that contains the `pom.xml`. +4. Make sure that vscode-xml has started in the VS Code window that vscode-xml is running in. To double check that its running, open an XML file and try completion (Ctrl+Enter). +5. In the VS Code window where your Java LemMinX extension project is open, open the debug view (Ctrl+Shift+D), select "Remote Debug Java LemMinX extension", and click the play triangle to start debugging: + + ![](./images/Extensions/DebugAttachRemote.png) + + If you get a connection refused error, it could mean that LemMinX is not running. + Make sure you are running vscode-xml and that you have opened an XML file. + It could also mean that a debug session has already been started. + +6. Debug + +#### Eclipse + +1. Open your Java LemMinX extension project in Eclipse + +2. Select "Run > Debug configurations". + It will open a window that looks like this: + + ![Debug configuration dialog, which presents a list of debug configuration items and the option to modify them](./images/Extensions/DebugConfigurations.png) + +3. Right click "Remote Java Application" and select "Add a new entry". Give the entry an appropriate name. + For the project field, select your Java LemMinX extension project. + Enter "localhost" as the Host, and for the port, enter "1054". + Click "Apply" to save the configuration. + + ![Debug configuration dialog, with a new Remote Java Application configuration](./images/Extensions/NewDebugConfiguration.png) + +4. Run vscode-xml with your Java LemMinX extension in VS Code. + To check if its running, open an XML file and try completion (Ctrl+Enter). +5. In Eclipse, reopen "Run > Debug configurations". Select the configuration you make in step 2, then click "Debug". + * If you get a connection refused error, it could mean that LemMinX is not running. + Make sure you are running vscode-xml and that you have opened an XML file. It could also mean that a debugging session is already running. +6. Debug + ## XML extension API (TypeScript) See [PR 292](https://github.com/redhat-developer/vscode-xml/pull/292) diff --git a/docs/images/Extensions/DebugAttachRemote.png b/docs/images/Extensions/DebugAttachRemote.png new file mode 100644 index 00000000..7026788a Binary files /dev/null and b/docs/images/Extensions/DebugAttachRemote.png differ diff --git a/docs/images/Extensions/DebugConfigurations.png b/docs/images/Extensions/DebugConfigurations.png new file mode 100644 index 00000000..0fdf06a0 Binary files /dev/null and b/docs/images/Extensions/DebugConfigurations.png differ diff --git a/docs/images/Extensions/NewDebugConfiguration.png b/docs/images/Extensions/NewDebugConfiguration.png new file mode 100644 index 00000000..f2c2fa7b Binary files /dev/null and b/docs/images/Extensions/NewDebugConfiguration.png differ