diff --git a/README.md b/README.md index 15e9872..65c4a6b 100644 --- a/README.md +++ b/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': '' } ])` @@ -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 diff --git a/docs/configuration.md b/docs/configuration.md index 14f5047..da7a120 100644 --- a/docs/configuration.md +++ b/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 diff --git a/python3/vimspector/debug_session.py b/python3/vimspector/debug_session.py index 61d7a6c..8d3e5c1 100644 --- a/python3/vimspector/debug_session.py +++ b/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( - 'Which launch configuration?', - sorted( configurations.keys() ) ) + # Find a single configuration with 'default' True and autoselect not False + defaults = { n: c for n, c in configurations.items() + 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 diff --git a/tests/testdata/cpp/simple/.vimspector.json b/tests/testdata/cpp/simple/.vimspector.json index 5eb06e1..93a7a60 100644 --- a/tests/testdata/cpp/simple/.vimspector.json +++ b/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}", - "logging": { - "engineLogging": true + "MImode": "${VIMSPECTOR_MIMODE}" + }, + "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": {