Add documentation for debugging LemMinX extensions

Closes redhat-developer#380

Signed-off-by: David Thompson <[email protected]>

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)