configure.js: Add llnode command

Add an llnode command script that invokes lldb and pre-loads the
plugin for ease of use.

PR-URL: #108
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Fedor Indutny <fedor@indutny.com>

Author: hhellyer

README.md

@@ -2,24 +2,45 @@
 
 [![Build Status](https://secure.travis-ci.org/nodejs/llnode.png)](http://travis-ci.org/nodejs/llnode)
 
-Node.js v4.x-v6.x C++ plugin for [LLDB](http://lldb.llvm.org) - a next generation, high-performance debugger.
+Node.js v4.x-v8.x C++ plugin for the [LLDB](http://lldb.llvm.org) debugger.
+
+The llnode plugin adds the ability to inspect JavaScript stack frames, objects,
+source code and more to the standard C/C++ debugging facilities when working
+with Node.js processes or core dumps in LLDB.
+
+### Quick start
+
+Start an lldb session with the llnode plugin pre-loaded:
+
+```bash
+npm install -g llnode
+llnode node -c core
+```
+
+- For more details on starting llnode see the [Usage](#usage) section.
+- To get started with the llnode commands see the [Commands](#commands) section.
 
 ## Demo
 
 https://asciinema.org/a/29589
 
 ## Install Instructions
 
-### Install with npm
+To use llnode you need to have the LLDB debugger installed.
+
+- On OS X lldb is installed as part of Xcode. You will need Xcode both to build and run llnode.
+- On Linux install the lldb package using your distributions package manager.
+
+### Global install with npm
 
 ```bash
-npm install llnode
+npm install -g llnode
 ```
 
 To use a particular build of lldb, use the `--lldb_exe` option:
 
 ```bash
-npm install --lldb_exe=`which lldb-3.9` llnode
+npm install --lldb_exe=`which lldb-3.9` -g llnode
 ```
 
 ### Install with Homebrew (OS X)
@@ -75,11 +96,29 @@ make -C out/ -j9
 sudo make install-linux
 ```
 
-## Usage
+## Loading the lldb plugin library.
+
+The simplest method is:
+```bash
+npm install -g llnode
+llnode
+```
+
+If you do a global install (npm install -g llnode) you can use the `llnode`
+shortcut script. This starts `lldb` and automatically issues the `plugin load` command.
+All parameters to the llnode script are passed directly to lldb. If you do not do a
+local install the shortcut will be in `node_modules/.bin/llnode`
+
+If you run either `make install-linux` or `make install-osx` the plugin will installed
+in the LLDB system plugin directory, in which case LLDB will load the plugin
+automatically on start-up. Using this may require additional permissions to be able to
+copy the plugin libary to the system plugin directory.
 
-The llnode plugin can be loaded into LLDB using the `plugin load` command.
-Alternatively it can be installed in the LLDB system plugin directory, in
-which case LLDB will load the plugin automatically on start-up.
+The llnode plugin can also be manually loaded into LLDB using the
+`plugin load` command within lldb.
+
+It does not matter whether the `plugin load` command is issued before or after
+loading a core dump or attaching to a process.
 
 ### OS X
 
@@ -106,22 +145,35 @@ To install the plugin in the LLDB system plugin directory, use the
 npm copy `node_modules/llnode/llnode.so` to
 `/usr/lib/lldb/plugins`.
 
+# Usage
+
 To use llnode with a core dump the core dump needs to be loaded into lldb
 along with the exact executable that created the core dump. The executable
-contains information that lldb and llnode need to make sense of the data in
-the core dump.
+contains information that lldb and the llnode plugin need to make sense of
+the data in the core dump.
 
-To load the core dump when starting lldb use:
+To load a core dump when starting llnode use:
 ```
-lldb /path/to/bin/node -c /path/to/core
+llnode /path/to/bin/node -c /path/to/core
 ```
 or to load the core dump after starting lldb:
 ```
-(lldb) target create /path/to/bin/node -c /path/to/core
+(llnode) target create /path/to/bin/node -c /path/to/core
 ```
 
-It does not matter whether the `plugin load` command is issued before or after
-loading a core dump.
+To use llnode against a live process:
+```
+llnode -- /path/to/bin/node script.js
+(llnode) run
+```
+This is ideal for debugging an npm package with native code.
+To debug a Node.js crash on uncaught exception:
+```
+llnode -- /path/to/bin/node --abort_on_uncaught_exception script.js
+(llnode) run
+```
+lldb will stop your process when it crashes. To see where it stopped use the
+v8 bt command. See the [Commands](#commands) section below for more commands.
 
 ### Commands
 
@@ -152,6 +204,7 @@ The following subcommands are supported:
                           * -v, --value expr     - all properties that refer to the specified JavaScript object (default)
                           * -n, --name  name     - all properties with the specified name
                           * -s, --string string  - all properties that refer to the specified JavaScript string value
+                          * --array-length num   - print maximum of `num` elements in array
 
       inspect         -- Print detailed description and contents of the JavaScript value.
 

package.json

@@ -6,6 +6,7 @@
   "directories": {
     "test": "test"
   },
+  "bin" : { "llnode" : "scripts/llnode.sh"},
   "//": "(Blame C++)",
   "scripts": {
     "preinstall": "node scripts/configure.js",

scripts/configure.js

@@ -107,6 +107,8 @@ fs.mkdirSync('tools');
 console.log(`Linking tools/gyp to ${gypDir}/gyp`);
 fs.symlinkSync(`${gypDir}/gyp`, 'tools/gyp');
 
+fs.writeFileSync(`${buildDir}/scripts/llnode.sh`, scriptText(lldbExe));
+
 // Exit with success.
 process.exit(0);
 
@@ -140,7 +142,7 @@ function getDarwinRelease() {
 }
 
 // Find the 'best' lldb to use. Either:
-// - the one specified by the user using npm --llnode_exe=... install llnode
+// - the one specified by the user using npm --lldb_exe=... install llnode
 // - the default lldb executable
 // - the higest known lldb version
 function getLldbExecutable() {
@@ -215,3 +217,28 @@ function getLinuxHeadersDir(version) {
   }
   return undefined;
 }
+
+function scriptText(lldbExe) {
+
+  let lib = 'llnode.so';
+  if (osName === 'Darwin') {
+    lib = 'llnode.dylib';
+  }
+
+  return `#!/bin/sh
+
+LLNODE_SCRIPT=\`node -p "path.resolve('$0')"\`
+
+SCRIPT_PATH=\`dirname $LLNODE_SCRIPT\`
+if [ \`basename $SCRIPT_PATH\` = ".bin" ]; then
+  # llnode installed locally in node_modules/.bin
+  LLNODE_PLUGIN="$SCRIPT_PATH/../llnode/${lib}"
+else
+  # llnode installed globally in lib/node_modules
+  LLNODE_PLUGIN="$SCRIPT_PATH/../lib/node_modules/llnode/${lib}"
+fi
+
+${lldbExe} --one-line "plugin load $LLNODE_PLUGIN" --one-line "settings set prompt '(llnode) '" $@
+`;
+
+}

scripts/llnode.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+echo "Place holder script for llnode"
+
+exit 1;