HenriqueBucher created this revision. HenriqueBucher added reviewers: JDevlieghere, clayborg. Herald added a project: All. HenriqueBucher requested review of this revision. Herald added a project: LLDB. Herald added a subscriber: lldb-commits.
Reformatted doc text so it is more or less around 80 columns limit - in markdown equivalent. Repository: rG LLVM Github Monorepo https://reviews.llvm.org/D135607 Files: lldb/tools/lldb-vscode/README.md
Index: lldb/tools/lldb-vscode/README.md =================================================================== --- lldb/tools/lldb-vscode/README.md +++ lldb/tools/lldb-vscode/README.md @@ -15,16 +15,16 @@ # Introduction The `lldb-vscode` tool creates a command line tool that implements the [Visual -Studio Code Debug API](https://code.visualstudio.com/docs/extensionAPI/api-debugging). -It can be installed as an extension for the Visual Studio Code and Nuclide IDE. -The protocol is easy to run remotely and also can allow other tools and IDEs to -get a full featured debugger with a well defined protocol. +Studio Code Debug API](https://code.visualstudio.com/docs/extensionAPI/api-debugging). It can be installed as an extension for the Visual Studio Code +and Nuclide IDE. The protocol is easy to run remotely and also can allow other tools +and IDEs to get a full featured debugger with a well defined protocol. # Installation for Visual Studio Code -Installing the plug-in involves creating a directory in the `~/.vscode/extensions` folder and copying the package.json file that is in the same directory as this -documentation into it, and copying to symlinking a lldb-vscode binary into -the `bin` directory inside the plug-in directory. +Installing the plug-in involves creating a directory in the `~/.vscode/extensions` +folder and copying the package.json file that is in the same directory as this +documentation into it, and copying to symlinking a lldb-vscode binary into the `bin` +directory inside the plug-in directory. If you want to make a stand alone plug-in that you can send to others on unix systems: @@ -47,8 +47,10 @@ $ rsync -av /path/to/a/built/LLDB.framework LLDB.framework ``` -You might need to create additional directories for the `liblldb.so` or `LLDB.framework` inside or next to the `bin` folder depending on how the [rpath](https://en.wikipedia.org/wiki/Rpath) is set in your `lldb-vscode` binary. By default the `Debug` builds of LLDB usually includes -the current executable directory in the rpath, so these steps should work for most people. +You might need to create additional directories for the `liblldb.so` or `LLDB.framework` +inside or next to the `bin` folder depending on how the [rpath](https://en.wikipedia.org/wiki/Rpath) is set in your `lldb-vscode` +binary. By default the `Debug` builds of LLDB usually includes the current executable +directory in the rpath, so these steps should work for most people. To create a plug-in that symlinks into your `lldb-vscode` in your build directory: @@ -59,18 +61,20 @@ $ ln -s /path/to/a/built/lldb-vscode ``` -This is handy if you want to debug and develope the `lldb-vscode` executable when adding features or fixing bugs. +This is handy if you want to debug and develope the `lldb-vscode` executable when +adding features or fixing bugs. # Configurations -Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations). This file -defines arguments that get passed to `lldb-vscode` and the configuration settings -control how the launch or attach happens. +Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations). This file defines +arguments that get passed to `lldb-vscode` and the configuration settings control how +the launch or attach happens. ## Launch Configuration Settings When you launch a program with Visual Studio Code you will need to create a [launch.json](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations) -file that defines how your program will be run. The JSON configuration file can contain the following `lldb-vscode` specific launch key/value pairs: +file that defines how your program will be run. The JSON configuration file can contain +the following `lldb-vscode` specific launch key/value pairs: |parameter |type|req | | |-------------------|----|:--:|---------| @@ -78,17 +82,17 @@ |**type** |string|Y| Must be "lldb-vscode". |**request** |string|Y| Must be "launch". |**program** |string|Y| Path to the executable to launch. -|**args** |[string]|| An array of command line argument strings to be passed to the program being launched. +|**args** |[string]|| An array of command line argument strings to be <br/>passed to the program being launched. |**cwd** |string| | The program working directory. -|**env** |dictionary| | Environment variables to set when launching the program. The format of each environment variable string is "VAR=VALUE" for environment variables with values or just "VAR" for environment variables with no values. +|**env** |dictionary| | Environment variables to set when launching <br/>the program. The format of each environment variable<br/>string is "VAR=VALUE" for environment variables with values <br/>or just "VAR" for environment variables with no values. |**stopOnEntry** |boolean| | Whether to stop program immediately after launching. -|**initCommands** |[string]| | LLDB commands executed upon debugger startup prior to creating the LLDB target. Commands and command output will be sent to the debugger console when they are executed. -|**preRunCommands** |[string]| | LLDB commands executed just before launching after the LLDB target has been created. Commands and command output will be sent to the debugger console when they are executed. -|**stopCommands** |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed. -|**exitCommands** |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed. -|**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends. Commands and command output will be sent to the debugger console when they are executed. -|**sourceMap** |[string[2]]| | Specify an array of path re-mappings. Each element in the array must be a two element array containing a source and destination pathname. -|**debuggerRoot** | string| |Specify a working directory to use when launching lldb-vscode. If the debug information in your executable contains relative paths, this option can be used so that `lldb-vscode` can find source files and object files that have relative paths. +|**initCommands** |[string]| | LLDB commands executed upon debugger startup prior <br/>to creating the LLDB target. Commands and command output <br/>will be sent to the debugger console when they are executed. +|**preRunCommands** |[string]| | LLDB commands executed just before launching after the LLDB <br/>target has been created. Commands and command output will be <br/>sent to the debugger console when they are executed. +|**stopCommands** |[string]| | LLDB commands executed just after each stop. Commands and <br/>command output will be sent to the debugger console when they <br/>are executed. +|**exitCommands** |[string]| | LLDB commands executed when the program exits. <br/> Commands and command output will be sent to the <br/>debugger console when they are executed. +|**terminateCommands** |[string]| | LLDB commands executed when the debugging session <br/>ends. Commands and command output will be sent to the <br/>debugger console when they are executed. +|**sourceMap** |[string[2]]| | Specify an array of path re-mappings. Each element in the <br/>array must be a two element array containing a source and <br/>destination pathname. +|**debuggerRoot** | string| |Specify a working directory to use when launching <br/>lldb-vscode. If the debug information in your executable <br/>contains relative paths, this option can be used so that <br/>`lldb-vscode` can find source files and object files that <br/>have relative paths. ## Attaching Settings @@ -105,16 +109,16 @@ |**name** |string |Y| A configuration name that will be displayed in the IDE. |**type** |string |Y| Must be "lldb-vscode". |**request** |string |Y| Must be "attach". -|**program** |string | | Path to the executable to attach to. This value is optional but can help to resolve breakpoints prior the attaching to the program. -|**pid** |number | | The process id of the process you wish to attach to. If **pid** is omitted, the debugger will attempt to attach to the program by finding a process whose file name matches the file name from **porgram**. Setting this value to `${command:pickMyProcess}` will allow interactive process selection in the IDE. +|**program** |string | | Path to the executable to attach to. This value is optional<br/> but can help to resolve breakpoints prior the attaching to the <br/>program. +|**pid** |number | | The process id of the process you wish to attach to. If **pid** <br/>is omitted, the debugger will attempt to attach to the program <br/>by finding a process whose file name matches the file name <br/>from **program**. Setting this value to `${command:pickMyProcess}` <br/>will allow interactive process selection in the IDE. |**stopOnEntry** |boolean| | Whether to stop program immediately after launching. |**waitFor** |boolean | | Wait for the process to launch. -|**initCommands** |[string]| | LLDB commands executed upon debugger startup prior to creating the LLDB target. Commands and command output will be sent to the debugger console when they are executed. -|**preRunCommands** |[string]| | LLDB commands executed just before launching after the LLDB target has been created. Commands and command output will be sent to the debugger console when they are executed. -|**stopCommands** |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed. -|**exitCommands** |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed. -|**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends. Commands and command output will be sent to the debugger console when they are executed. -|**attachCommands** |[string]| | LLDB commands that will be executed after **preRunCommands** which take place of the code that normally does the attach. The commands can create a new target and attach or launch it however desired. This allows custom launch and attach configurations. Core files can use `target create --core /path/to/core` to attach to core files. +|**initCommands** |[string]| | LLDB commands executed upon debugger startup prior to <br/>creating the LLDB target. Commands and command output <br/>will be sent to the debugger console when they are executed. +|**preRunCommands** |[string]| | LLDB commands executed just before launching after the <br/>LLDB target has been created. Commands and command output <br/>will be sent to the debugger console when they are executed. +|**stopCommands** |[string]| | LLDB commands executed just after each stop. Commands <br/>and command output will be sent to the debugger console when <br/>they are executed. +|**exitCommands** |[string]| | LLDB commands executed when the program exits. Commands <br/>and command output will be sent to the debugger console when <br/>they are executed. +|**terminateCommands** |[string]| | LLDB commands executed when the debugging session ends.<br/> Commands and command output will be sent to the debugger <br/>console when they are executed. +|**attachCommands** |[string]| | LLDB commands that will be executed after **preRunCommands** <br/>which take place of the code that normally does the attach. The<br/> commands can create a new target and attach or launch it however <br/>desired. This allows custom launch and attach configurations. Core <br/>files can use `target create --core /path/to/core` to attach <br/>to core files. ## Example configurations
_______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
