lldb/tools/lldb-vscode/README.md

   1
   2 # Table of Contents
   3
   4 - [Introduction](#Introduction)
   5 - [Installation](#Installation-Visual-Studio-Code)
   6 - [Configurations](#configurations)
   7         - [Launch Configuration Settings](#launch-configuration-settings)
   8         - [Attach Configuration Settings](#attach-configuration-settings)
   9         - [Example configurations](#example-configurations)
  10                 - [Launching](#launching)
  11                 - [Attach to process using process ID](#attach-using-pid)
  12                 - [Attach to process by name](#attach-by-name)
  13                 - [Loading a core file](#loading-a-core-file)
  14
  15 # Introduction
  16
  17 The `lldb-vscode` tool creates a command line tool that implements the [Visual
  18 Studio Code Debug API](https://code.visualstudio.com/docs/extensionAPI/api-debugging).
  19 It can be installed as an extension for the Visual Studio Code and Nuclide IDE.
  20 The protocol is easy to run remotely and also can allow other tools and IDEs to
  21 get a full featured debugger with a well defined protocol.
  22
  23 # Installation for Visual Studio Code
  24
  25 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
  26 documentation into it, and copying to symlinking a lldb-vscode binary into
  27 the `bin` directory inside the plug-in directory.
  28
  29 If you want to make a stand alone plug-in that you can send to others on unix systems:
  30
  31 ```
  32 $ mkdir -p ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0/bin
  33 $ cp package.json ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0
  34 $ cd ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0/bin
  35 $ cp /path/to/a/built/lldb-vscode .
  36 $ cp /path/to/a/built/liblldb.so .
  37 ```
  38
  39
  40 If you want to make a stand alone plug-in that you can send to others on macOS systems:
  41
  42 ```
  43 $ mkdir -p ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0/bin
  44 $ cp package.json ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0
  45 $ cd ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0/bin
  46 $ cp /path/to/a/built/lldb-vscode .
  47 $ rsync -av /path/to/a/built/LLDB.framework LLDB.framework
  48 ```
  49
  50 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
  51 the current executable directory in the rpath, so these steps should work for most people.
  52
  53 To create a plug-in that symlinks into your `lldb-vscode` in your build directory:
  54
  55 ```
  56 $ mkdir -p ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0/bin
  57 $ cp package.json ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0
  58 $ cd ~/.vscode/extensions/llvm-org.lldb-vscode-0.1.0/bin
  59 $ ln -s /path/to/a/built/lldb-vscode
  60 ```
  61
  62 This is handy if you want to debug and develope the `lldb-vscode` executable when adding features or fixing bugs.
  63
  64 # Configurations
  65
  66 Launching to attaching require you to create a [launch configuration](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations). This file
  67 defines arguments that get passed to `lldb-vscode` and the configuration settings
  68 control how the launch or attach happens.
  69
  70 ## Launch Configuration Settings
  71
  72 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)
  73 file that defines how your program will be run. The JSON configuration file can contain the following `lldb-vscode` specific launch key/value pairs:
  74
  75 |parameter          |type|req |         |
  76 |-------------------|----|:--:|---------|
  77 |**name**           |string|Y| A configuration name that will be displayed in the IDE.
  78 |**type**           |string|Y| Must be "lldb-vscode".
  79 |**request**        |string|Y| Must be "launch".
  80 |**program**        |string|Y| Path to the executable to launch.
  81 |**args**           |[string]|| An array of command line argument strings to be passed to the program being launched.
  82 |**cwd**            |string| | The program working directory.
  83 |**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.
  84 |**stopOnEntry**    |boolean| | Whether to stop program immediately after launching.
  85 |**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.
  86 |**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.
  87 |**stopCommands**   |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed.
  88 |**exitCommands**   |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed.
  89 |**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.
  90 |**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.
  91 |**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.
  92
  93 ## Attaching Settings
  94
  95 When attaching to a process using LLDB you can attach in a few ways
  96
  97 1. Attach to an existing process using the process ID
  98 2. Attach to an existing process by name
  99 3. Attach by name by waiting for the next instance of a process to launch
 100
 101 The JSON configuration file can contain the following `lldb-vscode` specific launch key/value pairs:
 102
 103 |parameter          |type    |req |         |
 104 |-------------------|--------|:--:|---------|
 105 |**name**           |string  |Y| A configuration name that will be displayed in the IDE.
 106 |**type**           |string  |Y| Must be "lldb-vscode".
 107 |**request**        |string  |Y| Must be "attach".
 108 |**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.
 109 |**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.
 110 |**stopOnEntry**    |boolean| | Whether to stop program immediately after launching.
 111 |**waitFor**        |boolean | | Wait for the process to launch.
 112 |**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.
 113 |**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.
 114 |**stopCommands**   |[string]| | LLDB commands executed just after each stop. Commands and command output will be sent to the debugger console when they are executed.
 115 |**exitCommands**   |[string]| | LLDB commands executed when the program exits. Commands and command output will be sent to the debugger console when they are executed.
 116 |**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.
 117 |**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.
 118
 119
 120 ## Example configurations
 121
 122 ### Launching
 123
 124 This will launch `/tmp/a.out` with arguments `one`, `two`, and `three` and
 125 adds `FOO=1` and `bar` to the environment:
 126
 127 ```javascript
 128 {
 129   "type": "lldb-vscode",
 130   "request": "launch",
 131   "name": "Debug",
 132   "program": "/tmp/a.out",
 133   "args": [ "one", "two", "three" ],
 134   "env": [ "FOO=1", "BAR" ],
 135 }
 136 ```
 137
 138 ### Attach using PID
 139
 140 This will attach to a process `a.out` whose process ID is 123:
 141
 142 ```javascript
 143 {
 144   "type": "lldb-vscode",
 145   "request": "attach",
 146   "name": "Attach to PID",
 147   "program": "/tmp/a.out",
 148   "pid": 123
 149 }
 150 ```
 151
 152 ### Attach by Name
 153
 154 This will attach to an existing process whose base
 155 name matches `a.out`. All we have to do is leave the `pid` value out of the
 156 above configuration:
 157
 158 ```javascript
 159 {
 160   "name": "Attach to Name",
 161   "type": "lldb-vscode",
 162   "request": "attach",
 163   "program": "/tmp/a.out",
 164 }
 165 ```
 166
 167 If you want to ignore any existing a.out processes and wait for the next instance
 168 to be launched you can add the "waitFor" key value pair:
 169
 170 ```javascript
 171 {
 172   "name": "Attach to Name (wait)",
 173   "type": "lldb-vscode",
 174   "request": "attach",
 175   "program": "/tmp/a.out",
 176   "waitFor": true
 177 }
 178 ```
 179
 180 This will work as long as the architecture, vendor and OS supports waiting
 181 for processes. Currently MacOS is the only platform that supports this.
 182
 183
 184 ### Loading a Core File
 185
 186 This loads the coredump file `/cores/123.core` associated with the program
 187 `/tmp/a.out`:
 188
 189 ```javascript
 190 {
 191   "name": "Load coredump",
 192   "type": "lldb-vscode",
 193   "request": "attach",
 194   "coreFile": "/cores/123.core",
 195   "program": "/tmp/a.out"
 196 }
 197 ```