Merge branch 'topic/gnattest-doc' into 'master'

Document how to work with multiple projects in the same workspace

Closes #1660

See merge request eng/ide/ada_language_server!2029

Author: eliericha

README.md

@@ -52,9 +52,16 @@ extension at
     - [Tasks](#tasks)
       - [Task Customization](#task-customization)
       - [Tasks for Project Mains](#tasks-for-project-mains)
+    - [Status Bar](#status-bar)
     - [Alire Support](#alire-support)
     - [GNATtest Support](#gnattest-support)
+      - [Using multi-root workspaces for test development](#using-multi-root-workspaces-for-test-development)
+      - [Limitations](#limitations)
     - [GNATcoverage Support](#gnatcoverage-support)
+    - [Cross and Embedded Support](#cross-and-embedded-support)
+      - [GNATemulator Support](#gnatemulator-support)
+      - [Remote Debugging](#remote-debugging)
+    - [Working with Multiple Projects in the Same VS Code Workspace](#working-with-multiple-projects-in-the-same-vs-code-workspace)
     - [Commands and Shortcuts](#commands-and-shortcuts)
       - [Ada: Go to other file](#ada-go-to-other-file)
       - [Ada: Add subprogram box](#ada-add-subprogram-box)
@@ -300,12 +307,17 @@ If you install GNATtest, the Ada & SPARK extension for VS Code will provide the
 
   <img src="doc/gnattest-results.png" width="500" alt="GNATtest Test Results"/>
 
-GNATtest support has the following known limitations:
+#### Using multi-root workspaces for test development
 
-* The extension relies on the default conventions of GNATtest such as the naming, location and object directory of the test harness project.
-  If those aspects are configured or altered manually, the features may no longer work.
+When developing tests, it is recommended to use the test harness project auto-generated by GNATtest.
+You can do so by editing the `ada.projectFile` setting to point to the test harness project.
+However to avoid switching back and forth between the main application project and the test harness project,
+see [Working with Multiple Projects in the Same VS Code Workspace](#working-with-multiple-projects-in-the-same-vs-code-workspace) for instructions on opening the test harness project in a separate VS Code window.
 
-* Language support such as navigation and auto-completion is limited when editing test sources. A workaround is to modify the `ada.projectFile` setting to point to the test harness project created by GNATtest. That should restore language support when developing tests.
+#### Limitations
+
+* If you use a separate window to load the test harness project and edit tests, you have to go back to the main application project to benefit from the integration with the Test Explorer view (e.g. listing and searching for tests, running tests, etc...).
+  This limitation is planned to be lifted.
 
 * Sections of test sources delimited by `begin read only` and `end read only` comments are not really protected from inadvertant edits.
   To ensure proper interactions with GNATtest, you must refrain from making edits in those sections.
@@ -375,6 +387,54 @@ Once your project is setup, just open the VS Code
 
 For more advanced use cases or if your program cannot be debugged remotely via GDB, you can try creating your custom VS Code debug launch configuration following [VS Code User's Guide for Launch Configurations](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations).
 
+### Working with Multiple Projects in the Same VS Code Workspace
+
+It is a possible for a workspace to contain multiple GPR projects.
+For example, this is a typical scenario when working with GNATtest which generates (potentially multiple) test harness projects that contain test and stub sources that interface with the application code.
+However, only one project can be loaded at a time with the `ada.projectFile` setting.
+So you may find yourself switching back and forth between projects which can quickly become cumbersome.
+
+This situation can be improved with [VS Code multi-root workspaces](https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces). For example, in a workspace containing `prj1.gpr` and `prj2.gpr` it is possible to define the following two multi-root workspace files:
+
+* `prj1.code-workspace`
+
+  ```json
+  {
+    "folders": [
+      {
+        "path": "."
+      }
+    ],
+    "settings": {
+      "ada.projectFile": "prj1.gpr"
+    }
+  }
+  ```
+
+* `prj2.code-workspace`
+
+  ```json
+  {
+    "folders": [
+      {
+        "path": "."
+      }
+    ],
+    "settings": {
+      "ada.projectFile": "prj2.gpr"
+    }
+  }
+  ```
+
+(while the name indicates _multi-root_, we are using a single root folder in each workspace)
+
+Each of these workspaces can be opened in a different VS Code window, allowing to work on both projects side by side.
+Alternatively, the root workspace materialized by `.vscode/settings.json` can be kept as the main workspace with `prj1.gpr`, and the other multi-root workspace is created as `prj2.code-workspace` for working with `prj2.gpr`.
+
+In the use case of GNATtest, this allows us to load the main application project in a window and the test harness project in another window, and work on both simultaneously.
+
+Note that a separate Ada Language Server instance is used for each VS Code window, so you might observe high memory consumption in this situation.
+
 ### Commands and Shortcuts
 
 The extension contributes commands and a few default key bindings.