diff --git a/README.md b/README.md index f2b1a76..60c446c 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,7 @@ For a tutorial and usage overview, take a look at the * [Human Mode](#human-mode) * [Usage](#usage) * [Launch and attach by PID:](#launch-and-attach-by-pid) + * [Launch with options](#launch-with-options) * [Breakpoints](#breakpoints) * [Stepping](#stepping) * [Variables and scopes](#variables-and-scopes) @@ -44,12 +45,16 @@ For a tutorial and usage overview, take a look at the * [C♯](#c) * [Go](#go) * [PHP](#php) + * [Debug web application](#debug-web-application) + * [Debug cli application](#debug-cli-application) * [JavaScript, TypeScript, etc.](#javascript-typescript-etc) * [Java - partially supported](#java---partially-supported) + * [Customisation](#customisation) + * [Changing the default signs](#changing-the-default-signs) * [FAQ](#faq) * [License](#license) - + @@ -485,6 +490,36 @@ let g:vimspector_enable_mappings = 'HUMAN' * Create `vimspector.json`. See [below](#supported-languages). * `:call vimspector#Launch()` and select a configuration. +### Launch with options + +To launch a specific debug configuration, or specify [replacement +variables][vimspector-ref-var] for the launch, you can use: + +* `:call vimspector#LaunchWithSettings( dict )` + +The argument is a `dict` with the following keys: + +* `configuration`: (optional) Name of the debug configuration to launch +* ``: (optional) Name of a variable to set + +This allows for some intergration and automation. For example, if you have a +configuration named `Run Test` that contains a [replacement +variable][vimspector-ref-var] named `${Test}` you could write a mapping which +ultimately executes: + +```viml +vimspector#LaunchWithSettings( #{ configuration: 'Run Test' + \ Test: 'Name of the test' } ) +``` + +This would start the `Run Test` configuration with `${Test}` set to `'Name of +the test'` and Vimspector would _not_ prompt the user to enter or confirm these +things. + +See [this issue](https://github.com/puremourning/vimspector/issues/97) for +another example where it can be used to specify the port to connect the [java +debugger](#java---partially-supported) + ## Breakpoints * Use `vimspector#ToggleBreakpoint()` to set/disable/delete a line breakpoint. @@ -552,9 +587,12 @@ To close the debugger, use: # Debug adapter configuration -For more information on the configuration of `.vimspector.json`, take a look at +For an introduction to the configuration of `.vimspector.json`, take a look at the Getting Started section of the [Vimspector website][website]. +For full explanation, including how to use variables, substitutions and how to +specify exception breakpoints, see [the docs](vimspector-ref). + Current tested with the following debug adapters. ## C, C++, Rust, etc. @@ -936,8 +974,10 @@ sign define vimspectorPC text=🔶 texthl=SpellBad necessarily be easy to work out what to put in the `.vimspector.json`. As you can see above, some of the servers aren't really editor agnostic, and require very-specific unique handling. -3. How do i stop it starting a new Terminal.app on macOS? See [this +3. How do I stop it starting a new Terminal.app on macOS? See [this comment](https://github.com/puremourning/vimspector/issues/90#issuecomment-577857322) +4. Can I specify answers to the annoying questions about exception breakpoints + in my `vimspector.json` ? Yes, see [here][vimspector-ref-exception]. # License @@ -951,3 +991,6 @@ Copyright © 2018 Ben Jackson [website]: https://puremourning.github.io/vimspector-web/ [delve]: https://github.com/go-delve/delve [delve-install]: https://github.com/go-delve/delve/tree/master/Documentation/installation +[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 diff --git a/docs/configuration.md b/docs/configuration.md index 97418e1..3c4a827 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -6,6 +6,23 @@ title: Configuration This document defines the supported format for project and adapter configuration for Vimspector. + + * [Concepts](#concepts) + * [Debug adapter configuration](#debug-adapter-configuration) + * [Debug profile configuration](#debug-profile-configuration) + * [Replacements and variables](#replacements-and-variables) + * [Configuration Format](#configuration-format) + * [Files and locations](#files-and-locations) + * [Adapter configurations](#adapter-configurations) + * [Debug configurations](#debug-configurations) + * [Exception breakpionts](#exception-breakpionts) + * [Predefined Variables](#predefined-variables) + * [Appendix: Editor configuration](#appendix-editor-configuration) + + + + + ## Concepts As Vimspector supports debugging arbitrary projects, you need to tell it a few @@ -235,6 +252,35 @@ typical example looks like this: } ``` +### Exception breakpionts + +Debug adapters have arbitrary configuration for exception breakpoints. Normally +this is presented as a series of question to the user on startnig the debug +session. The question includes the name of the exception breakpoint option, +the default and the list of valid responses (usually `Y` or `N`). + +You can pre-configure the answers to these questions in the `breakpoints` +section of the debug configuration. For each question, take the name provided +and configure the response `exception` mapping in the `breakpoints` mapping. If +the configured response is empty string, the debug adapter default will be used. + +Referring to the above example, the following tells the debug adapter to use the +default value for `caught` exceptoins and to break on `uncaught` exception: + +``` +{ + "configurations": { + "example-debug-configuration": { + "adapter": "example-adapter-name", + "breakpoints": { + "exception": { + "caught": "", + "uncaught": "Y" + } + }, + ... +``` + ## Predefined Variables The following variables are provided: