Allow default configuraiton to be specified; document selection

README.md

@@ -601,6 +601,19 @@ See [our YouCompleteMe integration guide](#usage-with-youcompleteme) for
 another example where it can be used to specify the port to connect the [java
 debugger](#java---partially-supported)
 
+### Debug configuration selection
+
+Vimspector uses the following logic to choose a configuration to launch:
+
+1. If a configuration was specified in the launch options (as above), use that.
+2. Otherwise if there's only one configuration and it doesn't have `autoselect`
+   set to `false`, use that.
+3. Otherwise if there's exactly one configuration with `default` set to `true`
+   and without `autoselect` set to `false`, use that.
+4. Otherwise, prompt the user to select a configuration.
+
+See [the reference guide][vimspector-ref-config-selection] for details.
+
 ## Breakpoints
 
 * Use `vimspector#ToggleBreakpoint([ { 'condition': '<condition expr>' } ])`
@@ -1366,6 +1379,7 @@ Copyright © 2018 Ben Jackson
 [vimspector-ref]: https://puremourning.github.io/vimspector/configuration.html
 [vimspector-ref-var]: https://puremourning.github.io/vimspector/configuration.html#replacements-and-variables
 [vimspector-ref-exception]: https://puremourning.github.io/vimspector/configuration.html#exception-breakpoints
+[vimspector-ref-config-selection]: https://puremourning.github.io/vimspector/configuration.html#configuration-selection
 [debugpy]: https://github.com/microsoft/debugpy
 [YouCompleteMe]: https://github.com/ycm-core/YouCompleteMe#java-semantic-completion
 [remote-debugging]: https://puremourning.github.io/vimspector/configuration.html#remote-debugging-support

docs/configuration.md

@@ -321,6 +321,62 @@ typical example looks like this:
 }
 ```
 
+### Configuration selection
+
+When starting debugging, you can specify which debug configuration to launch
+with `call vimspector#LaunchWithSettings( #{ configuration: 'name here' } )`.
+
+Otherwise, if there's only one configuration found, Vimspector will use that
+configuration, unless it contains a key `"autoselect": false`.
+
+If multiple debug configurations are found, and no explicit configuration was
+selected on Launch, the user is prompted to select a configuration, unless a
+single debug configuration is found with a key `"default": true`.
+
+#### Specifying a default configuration
+
+As noted, you can specify a default configuration with `"default": true`:
+
+```json
+{
+  "configurations": {
+    "use this one": {
+      "default": true,
+      "adapter": " ... ",
+      "configuation": {
+        // ...
+      }
+    },
+    "don't use this one": {
+      // ...
+    }
+  }
+}
+```
+
+If multiple conifigurations are found with `default` set to `true`, then the
+user is prompted anyway.
+
+#### Preventing automatic selection
+
+If you don't want a configuration to be selected automatically, then set
+`"autoselect": false`. This particularly useful for configurations in the
+central (as opposed to project-local) directory. For example:
+
+```json
+  "configurations": {
+    "Don't use this by default!": {
+      "autoselect": false,
+      "adapter": " ... ",
+      "configuation": {
+        // ...
+      }
+    }
+  }
+```
+
+Setting `autoselect` to `false` overrides setting `default` to `true`.
+
 ### Exception breakpionts
 
 Debug adapters have arbitrary configuration for exception breakpoints. Normally
@@ -426,12 +482,12 @@ where the development is done on one host and the runtime is
 some other host, account, container, etc.
 
 In order for it to work, you have to set up passwordless SSH between the local
-and remote machines/accounts. Then just tell Vimsector how to remotely launch
+and remote machines/accounts. Then just tell Vimspector how to remotely launch
 and/or attach to the app.
 
 This is presented as examples with commentary, as it's a fairly advanced/niche
 case. If you're not already familiar with remote debugging tools (such as
-gdbserver) or not familar with ssh or such, you might need to independently
+gdbserver) or not familiar with ssh or such, you might need to independently
 research that.
 
 Vimspector's tools are intended to automate your existing process for setting

python3/vimspector/debug_session.py

@@ -125,9 +125,17 @@ class DebugSession( object ):
            next( iter( configurations.values() ) ).get( "autoselect", True ) ):
       configuration_name = next( iter( configurations.keys() ) )
     else:
-      configuration_name = utils.SelectFromList(
+      # Find a single configuration with 'default' True and autoselect not False
-        'Which launch configuration?',
+      defaults = { n: c for n, c in configurations.items()
-        sorted( configurations.keys() ) )
+                   if c.get( 'default', False ) is True
+                   and c.get( 'autoselect', True ) is not False }
+
+      if len( defaults ) == 1:
+        configuration_name = next( iter( defaults.keys() ) )
+      else:
+        configuration_name = utils.SelectFromList(
+          'Which launch configuration?',
+          sorted( configurations.keys() ) )
 
     if not configuration_name or configuration_name not in configurations:
       return

tests/testdata/cpp/simple/.vimspector.json

@@ -1,17 +1,38 @@
 {
   "configurations": {
-    "cpptools-run": {
+    "run-to-entry": {
       "adapter": "vscode-cpptools",
+      // This makes this configuration the default. Only one default can be set
+      // (having two is the same as having none)
+      "default": true,
       "configuration": {
         "request": "launch",
         "program": "${workspaceRoot}/${fileBasenameNoExtension}",
         "externalConsole": false,
         "stopAtEntry": true,
         "stopOnEntry": true,
-        "MImode": "${VIMSPECTOR_MIMODE}",
+        "MImode": "${VIMSPECTOR_MIMODE}"
-        "logging": {
+      },
-          "engineLogging": true
+      "breakpoints": {
+        "exception": {
+          "cpp_catch": "",
+          "cpp_throw": "",
+          "objc_catch": "",
+          "objc_throw": "",
+          "swift_catch": "",
+          "swift_throw": ""
         }
+      }
+    },
+    "run-to-breakpoint": {
+      "adapter": "vscode-cpptools",
+      "configuration": {
+        "request": "launch",
+        "program": "${workspaceRoot}/${fileBasenameNoExtension}",
+        "externalConsole": false,
+        "stopAtEntry": false,
+        "stopOnEntry": false,
+        "MImode": "${VIMSPECTOR_MIMODE}"
       },
       "breakpoints": {
         "exception": {