Merge pull request #1 from rnchamberlain/llnode-update

Additional documentation for the llnode plugin

README.md

@@ -12,6 +12,7 @@
 | wip: [core dumps](core-dumps.md) |
 | wip: [tracking (de)optimizations](optimizations.md) |
 | tbd: [heap dumps](tbd.md) |
+| tbd: [native debuggers (gdb and lldb)](tbd.md) |
 | **External links** |
 | [read this to really understand how asynchronous code runs](https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick/) |
 

core-dumps.md

@@ -18,8 +18,9 @@ If you didn't encounter a core dump before, it's probably because the operating
   - set `--abort-on-uncaught-exception` to dump core on crash
   - call `process.abort()`
 - get the `core` file
-- segment it with a script from llnode `./llnode/scripts/readelf2segments.py ./core > core.ranges`
-- let lldb know where to look `export LLNODE_RANGESFILE=core.ranges`
+- if you are using lldb version 3.8 (not needed if you are using lldb version 3.9 or later):
+  - segment it with a script from llnode `./llnode/scripts/readelf2segments.py ./core > core.ranges`
+  - let lldb know where to look `export LLNODE_RANGESFILE=core.ranges`
 - run `lldb -c core`
 - use `v8` commands to analyze
 

llnode.md

@@ -14,15 +14,47 @@ It's great that lldb+llnode can be used to read diagnostics from node, it used t
 
 ## Notes on installation
 
-[https://github.com/nodejs/llnode](https://github.com/nodejs/llnode)
+First install lldb using apt-get, then install the llnode plugin from npm or from github:
 
-Use install instructions, `npm install -g llnode` doesn't seem to work yet.
-But I had no trouble building according to instructions.
+[https://npmjs.org/package/llnode](https://www.npmjs.org/package/llnode)
 
-You'll need to install lldb too.
+or
+[https://github.com/nodejs/llnode](https://github.com/nodejs/llnode)
 
+TO install the plugin use `npm install llnode` or follow the build instructions in the github project.
 
+Note that lldb supports the use of a system plugin directory (`/usr/lib/lldb/plugins` on Linux). By installing a plugin in the system plugin directory you avoid having to run the lldb `plugin load llnode.so` command in each lldb session. The npm install does not add the llnode plugin to the system plugin directory. You can either copy the plugin: `sudo cp llnode.so /usr/lib/lldb/plugins` or if you are building from the github repository, install it using the `sudo make install-linux` build step. 
+
+*A global npm install of llnode, i.e. `npm install -g llnode`, does not work right now. Maybe we should raise an issue on llnode to have the -g install do the copy to the system plugin directory. It would need to run as sudo/root.*
 
 *It should work on all flavors of ubuntu and most other distros with any version of lldb starting at 3.8. If you find out more, feel free to PR here*
 
 *On 2017-02-03 I managed to install lldb-3.8 with latest llnode in xubuntu 16.04.1 kernel 4.4.0-62-generic x86_64*
+
+## llnode commands
+
+| Task                                     | Command                                                                              |
+|------------------------------------------|--------------------------------------------------------------------------------------|
+| Display the help                         | v8 help                                                                              |
+| Display the JavaScript and C++ stack     | v8 bt [<number of frames >]                                                    |
+|                                          | output includes source file, line number, object addresses                           |
+|                                          | display source code using ‘frame select  <frame number>’ then ‘v8 source list’ |
+| List objects in the JavaScript heap      | v8 findjsobjects                                                                     |
+|                                          | provides number of objects, total size and type name                                 |
+| Display a JavaScript object              | v8 print  <object address> or v8 inspect [-m -s -F] <object address>     |
+|                                          | provides constructor name, property names and values                                 |
+|                                          | -m option prints the object's map address                                            |
+|                                          | -s option prints source code for function objects                                    |
+|                                          | –F prints full string values without truncation                                      |
+| Find JavaScript objects by type name     | v8 findjsinstances [-m -s -F] <type name>                                      |
+|                                          | same output options as the ‘v8 inspect’ command                                      |
+| Display the constructor for an object    | v8 inspect  <object address>                                                   |
+| Display JavaScript source code           | v8 inspect -s  <function address>                                              |
+|                                          | or use ‘v8 source list’ for current stackframe, see ‘v8 bt’ above                    |
+| Find JavaScript objects by reference     | v8 findrefs [-v -n -s] <object address> or <name> or <string>      |
+|                                          | -v option (default) finds objects that reference a specified object                  |
+|                                          | -n option finds objects that reference a specified property name                     |
+|                                          | -s option finds objects that reference a specified string                            |
+| Display raw address of buffer memory     | v8 inspect <buffer object address>                                             |
+| Display Node.js information summary      | v8 nodeinfo                                                                          |
+