Merge remote branch 'origin/master' into edge

Author: automatic-merge

README.md

@@ -137,11 +137,33 @@ Here are some links that will help you get familiar with the VS Code extension f
 
 ### Configuration
 
-You can configure the extension via the `.vscode/settings.json` workspace settings file or the [multi-root workspace file](https://code.visualstudio.com/docs/editor/multi-root-workspaces).
-More information about settings and the different ways that can be used to specify them can be found [here](doc/settings.md).
+[ALS settings](doc/settings.md) can be specified in various ways. For example:
+
+- A `.als.json` file at the root of the workspace.
+- A global user configuration file `$HOME/.config/als/config.json`
+- The `.vscode/settings.json` VS Code workspace settings file.
+- A [multi-root VS Code workspace file](https://code.visualstudio.com/docs/editor/multi-root-workspaces)
+- The User or Remote or other VS Code [scopes of of settings](https://code.visualstudio.com/docs/configure/settings#_settings-precedence)
+
+The `.als.json` file is the preferred method of defining workspace-specific settings because it applies in any IDE or editor that uses ALS. More information about configuration files can be found [here](doc/settings.md).
 
 Here is an example config file that sets the project file to use and the scenario variables, as well as other useful settings (charset, whether we should show file diagnostics etc.):
 
+```json
+{
+   "projectFile": "gnatcov.gpr",
+   "scenarioVariables": {
+      "BINUTILS_BUILD_DIR": "/null",
+      "BINUTILS_SRC_DIR": "/null"
+   },
+   "defaultCharset": "utf-8",
+   "adaFileDiagnostics": false,
+   "renameInComments": false
+}
+```
+
+Alternatively, the ALS can be configured in the VS Code settings UI or in the JSON settings files. For example:
+
 ```json
 {
    "ada.projectFile": "gnatcov.gpr",
@@ -333,8 +355,8 @@ program using GNATemulator.
 <img src="doc/media/gnatemu-debug-codelens.gif" width="800" alt="Debug with GNATemulator CodeLens" />
 
 The port used by the debugger launched by VS Code to connect to the running GNATemulator instance
-is the one specified via the `Emulator'Debug_Port` project attribute, so make sure it is set before
-running the dedicated GNATemulator command/CodeLens.
+is the one specified via the `Emulator'Debug_Port` project attribute: when not set, the extension
+will fallback on `localhost:1234` (GNATemulator's default debug port).
 
 Note that GNATemulator is not available for all GNAT embedded toolchains. For more information about GNATemulator itself and its availabilty please refer to the [GNATemulator User's Guide](https://docs.adacore.com/gnatemulator-docs/gnatemulator.html).
 
@@ -450,6 +472,8 @@ configure the Ada Language Server with `:CocConfig`:
 }
 ```
 
+Alternatively to the above settings section, workspace-specific [ALS Settings](doc/settings.md) such as the `projectFile` can be provided in a `.als.json` file at the root of the workspace.
+
 ### Integration with vim-lsp
 
 If you want to integrate the Ada Language Server into vim, you can use the
@@ -464,13 +488,12 @@ if executable('ada_language_server')
         \ 'name': 'ada_language_server',
         \ 'cmd': ['ada_language_server'],
         \ 'allowlist': ['ada'],
-        \ 'workspace_config': {'ada': {
-        \     'projectFile': "project.gpr",
-        \     'scenarioVariables': {"ARCH": "x86_64-pc-linux-gnu"}}},
         \ })
 endif
 ```
 
+Workspace-specific [ALS Settings](doc/settings.md) such as the `projectFile` can be provided in a `.als.json` file at the root of the workspace.
+
 ### Integration with LanguageClient-Neovim
 
 If you want to integrate the Ada Language Server into Neovim, you can use the
@@ -487,33 +510,7 @@ let g:LanguageClient_serverCommands = {
 " if you already have LanguageClient_serverCommands, just add a line for ada.
 ```
 
-To configure the Ada Language Server for a specific workspace/project, you can
-use the `.vim/settings.json` file. It is mandatory as soon as you want to use a
-specific `.gpr` project file.
-
-This is the way to specify a project file, eg. you cannot open a project file
-another way.
-See the setting list [here](doc/settings.md).
-
-Here is an example of a settings file:
-
-```json
-{
-    "ada.projectFile": "project.gpr",
-    "ada.scenarioVariables": {
-        "GLFW_Version": "3",
-        "GLFW_Lib": "-lglfw",
-        "Windowing_System": "x11"
-    }
-}
-```
-
-The location where the `.vim` folder is located will determine the relative
-path of the project file (so no need to prefix with `..`). When vim is opened
-in the folder containing this `.vim` directory, it will use those settings for
-the language server *even for files which might have nothing to do with that
-specific project*, so this needs to be taken into account. Ultimately what this
-means is that the configuration is determined by where you open vim.
+Workspace-specific [ALS Settings](doc/settings.md) such as the `projectFile` can be provided in a `.als.json` file at the root of the workspace.
 
 ### Integration with Neovim's built-in LSP client
 
@@ -533,7 +530,7 @@ the lsp client an absolute path to the ALS executable:
 require('lspconfig').ada_ls.setup{ cmd = "/path/to/als/executable" }
 ```
 
-Configuring the language server's settings can be achieved like this:
+Configuring the language server's settings globally can be achieved like this:
 
 ```lua
 require('lspconfig').ada_ls.setup{
@@ -546,13 +543,16 @@ require('lspconfig').ada_ls.setup{
 }
 ```
 
-The Ada Language Server's settings are described [here](doc/settings.md).
-Configuring neovim to use project-specific settings is described neovim's
+Workspace-specific [ALS Settings](doc/settings.md) such as the `projectFile` can be provided in a `.als.json` file at the root of the workspace.
+
+Alternatively, workspace-specific settings can also be configured as per the
 [lspconfig wiki](https://github.com/neovim/nvim-lspconfig/wiki/Project-local-settings)
 
 ### Integration with emacs lsp-mode
 
-The configuration for each project can be provided using a `.dir-locals.el`
+Workspace-specific [ALS Settings](doc/settings.md) such as the `projectFile` can be provided in a `.als.json` file at the root of the workspace.
+
+Alternatively the configuration for each project can be provided using a `.dir-locals.el`
 file defined at the root of each project.
 
 The scenario variables should be declared in your `.emacs` or any loaded
@@ -595,10 +595,9 @@ Starting with version `4.9`, QtCreator supports a LSP plugin. Follow
 [the official documentation](https://doc.qt.io/qtcreator/creator-language-servers.html)
 to configure the Ada Language Server in this plugin. Make sure to set `Startup behavior`
 to `Start Server per Project`, otherwise QtCreator won't provide the project root to
-the Ada Language Server. QtCreator doesn't send any configuration request to the language server, so the only
-option to enable project support is to have a single `.gpr` file in the QtCreator
-project folder. For a projectless configuration, you could also place all Ada sources in
-the project root folder, this should work as well.
+the Ada Language Server.
+
+Workspace-specific [ALS Settings](doc/settings.md) such as the `projectFile` can be provided in a `.als.json` file at the root of the workspace.
 
 ## Refactoring Tools
 

doc/settings.md

@@ -4,7 +4,7 @@
 
 The ALS loads configuration settings from different sources. All configuration sources are loaded in the following order:
 
-1. A global user configuration file `$XDG_CONFIG_HOME/als/config.json`, if it exists.
+1. A global user configuration file `$XDG_CONFIG_HOME/als/config.json`, if it exists. The path [defaults](https://specifications.freedesktop.org/basedir-spec/0.8/#variables) to `$HOME/.config/als/config.json` if `XDG_CONFIG_HOME` is not set.
 
 1. A workspace-specific `.als.json` file in the directory where ALS is spawned, if it exists.
 

integration/vscode/ada/README.md

@@ -33,14 +33,12 @@ This extension **does not include a compiler nor additional tools**. Nonetheless
 | | Debug                | ✅ |
 | **GNAT DAS** | | |
 | | Test                | ✅ |
-| | Code Coverage       | 🚧 |
+| | Code Coverage       | ✅ |
 | **GNAT SAS** | | |
 | | Static Analysis     |       ✅            |
 | **SPARK** | | |
 | | Formal Proof        |       ✅          |
 
-🚧 _= The integration of this tool feature in Visual Studio Code is in progress._
-
 ## Getting Additional Tools
 
 For a fully operational development environment you can obtain a compiler and/or other tools from the following channels.

integration/vscode/ada/src/commands.ts

@@ -726,6 +726,7 @@ async function buildAndDebugSpecifiedMain(
     const adaMain = await findAdaMain(main.fsPath);
     const target = await adaExtState.getTargetPrefix();
     const debugServerAddress = await adaExtState.getDebugServerAddress(useGNATemulator);
+
     if (adaMain) {
         /**
          * The vscode API doesn't provide a way to list both automatically
@@ -762,6 +763,17 @@ async function buildAndDebugSpecifiedMain(
         if (matchingConfig) {
             logger.debug('Found matching config: ' + JSON.stringify(matchingConfig, null, 2));
 
+            // No debug server address specified in matching debug configuration: fallback
+            // to 'localhost:1234' to match GNATemulator's default debug port.
+            if (!matchingConfig.miDebuggerServerAddress && useGNATemulator) {
+                const fallbackDebugServerAddress = 'localhost:1234';
+                logger.debug(
+                    `No debug server address specified in debug configuration for GNATemulator:
+ use '${fallbackDebugServerAddress}' as a fallback`,
+                );
+                matchingConfig.miDebuggerServerAddress = 'localhost:1234';
+            }
+
             // Trying to debug via GNATemulator: run the main via GNATemulator in debug mode
             // before starting the debug session
             if (useGNATemulator) {