JS API: initial implementation

JSAPI.md

@@ -0,0 +1,55 @@
+```js
+class LLNode {
+  /**
+   * @param {string} dump path to the coredump
+   * @param {string} executable path to the node executable
+   * @returns {LLNode} an LLNode instance
+   */
+  static fromCoreDump(dump, executable) {}
+
+  /**
+   * @returns {string} SBProcess information
+   */
+  getProcessInfo() {}
+
+  /**
+   * @typedef {object} Frame
+   * @property {string} function
+   * 
+   * @typedef {object} Thread
+   * @property {number} threadId
+   * @property {number} frameCount
+   * @property {Frame[]} frames
+   * 
+   * @typedef {object} Process
+   * @property {number} pid
+   * @property {string} state
+   * @property {number} threadCount
+   * @property {Thread[]} threads
+   * 
+   * @returns {Process} Process data
+   */
+  getProcessobject() {}
+
+  /**
+   * @typedef {object} HeapInstance
+   * @property {string} address
+   * @property {string} value
+   * 
+   * @typedef {object} HeapType
+   * @property {string} typeName
+   * @property {string} instanceCount
+   * @property {string} totalSize
+   * @property {Iterator<HeapInstance>} instances
+   * 
+   * @returns {HeapType[]}
+   */
+  getHeapTypes() {}
+
+  /**
+   * TODO: rematerialize object
+   * @returns {HeapInstance}
+   */
+  getobjectAtAddress(address) {}
+}
+```

Makefile

@@ -5,7 +5,7 @@ all:
 	@echo "Please take a look at README.md"
 
 .PHONY: install-osx
-install-osx:
+install-osx: plugin
 	mkdir -p ~/Library/Application\ Support/LLDB/PlugIns/
 	cp -rf ./llnode.dylib \
 		~/Library/Application\ Support/LLDB/PlugIns/
@@ -15,7 +15,7 @@ uninstall-osx:
 	rm ~/Library/Application\ Support/LLDB/PlugIns/llnode.dylib
 
 .PHONY: install-linux
-install-linux:
+install-linux: plugin
 	mkdir -p /usr/lib/lldb/plugins
 	cp -rf ./llnode.so /usr/lib/lldb/plugins
 
@@ -37,6 +37,10 @@ plugin: configure
 	node-gyp rebuild
 	node scripts/cleanup.js
 
+.PHONY: addon
+addon: configure
+	node-gyp rebuild
+
 .PHONY: _travis
 _travis:
 	TEST_LLDB_BINARY="$(TEST_LLDB_BINARY)" \
@@ -49,4 +53,4 @@ clean:
 	$(RM) -r build
 	$(RM) config.gypi
 	$(RM) lldb
-	$(RM) llnode.so llnode.dylib
+	$(RM) addon.node llnode.so llnode.dylib

binding.gyp

@@ -7,7 +7,8 @@
   "variables": {
       # gyp does not appear to let you test for undefined variables, so define
       # lldb_lib_dir as empty so we can test it later.
-      "lldb_lib_dir%": ""
+      "lldb_lib_dir%": "",
+      "lldb_lib_so%": ""
   },
 
   "target_defaults": {
@@ -63,5 +64,41 @@
       "src/llv8-constants.cc",
       "src/llscan.cc",
     ]
+  }, {
+    "target_name": "addon",
+    "type": "loadable_module",
+    "include_dirs": [
+      "<!(node -e \"require('nan')\")"
+    ],
+    "sources": [
+      "src/addon.cc",
+      "src/llnode_module.cc",
+      "src/llnode_api.cc",
+      "src/llv8.cc",
+      "src/llv8-constants.cc",
+      "src/llscan.cc"
+    ],
+    "conditions": [
+      [ "OS=='linux' or OS=='freebsd'", {
+        "conditions": [
+          # If we could not locate the lib dir, then we will have to search
+          # from the global search paths during linking and at runtime
+          [ "lldb_lib_dir != ''", {
+            "ldflags": [
+              "-L<(lldb_lib_dir)",
+              "-Wl,-rpath,<(lldb_lib_dir)"
+            ]
+          }],
+          # If we cannot find a non-versioned library liblldb(-x.y).so,
+          # then we will have to link to the versioned library
+          # liblldb(-x.y).so.z loaded by the detected lldb executable
+          [ "lldb_lib_so != ''", {
+            "libraries": ["<(lldb_lib_so)"]
+          }, {
+            "libraries": ["-l<(lldb_lib)"]
+          }]
+        ]
+      }]
+    ]
   }],
 }

index.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const addon = require('bindings')('addon');
+const fromCoredump = addon.fromCoredump;
+const LLNodeHeapType = addon.LLNodeHeapType;
+const nextInstance = addon.nextInstance;
+
+function *next() {
+  let instance;
+  while (instance = nextInstance(this)) {
+    yield instance;
+  }
+}
+
+Object.defineProperty(LLNodeHeapType.prototype, 'instances', {
+  enumerable: false,
+  configurable: false,
+  get: function() {
+    return {
+      [Symbol.iterator]: next.bind(this)
+    }
+  }
+});
+
+module.exports = {
+  fromCoredump
+}

package.json

@@ -2,7 +2,7 @@
   "name": "llnode",
   "version": "1.7.0",
   "description": "Node.js plugin for LLDB",
-  "main": "no-entry-sorry.js",
+  "main": "index.js",
   "directories": {
     "test": "test"
   },
@@ -24,7 +24,8 @@
     "binding.gyp",
     "llnode.gypi",
     "src/",
-    "scripts/"
+    "scripts/",
+    "index.js"
   ],
   "keywords": [
     "llnode",
@@ -40,5 +41,9 @@
   "homepage": "https://github.com/nodejs/llnode#readme",
   "devDependencies": {
     "tape": "^4.4.0"
+  },
+  "dependencies": {
+    "bindings": "^1.3.0",
+    "nan": "^2.7.0"
   }
 }

scripts/configure.js

@@ -45,6 +45,9 @@ function configureInstallation(osName, buildDir) {
     if (installation.libDir) {
       config.variables['lldb_lib_dir%'] = installation.libDir;
     }
+    if (installation.libPath) {
+      config.variables['lldb_lib_so%'] = installation.libPath;
+    }
     config.variables['lldb_lib%'] = installation.libName;
   } else if (osName === 'FreeBSD') {
     installation = require('./freebsd').getLldbInstallation();

scripts/linux.js

@@ -85,7 +85,7 @@ function getIncludeDir(llvmConfig) {
  * undefined, the shared library will be searched from the global search paths
  * @param {string} lldbExe Path to the corresponding lldb executable
  * @param {string|undefined} llvmConfig Path to llvm-config, if it's installed
- * @returns {{dir:string, name:string}}
+ * @returns {{dir:string|undefined, name:string, so: string|undefined}}
  */
 function getLib(lldbExe, llvmConfig) {
   // First look for the libraries in the directory returned by
@@ -95,7 +95,7 @@ function getLib(lldbExe, llvmConfig) {
         llvmConfig, ['--libdir']
     ).toString().trim();
     if (fs.existsSync(path.join(libDir, 'liblldb.so'))) {
-      return { dir: libDir, name: 'lldb' };
+      return { dir: libDir, name: 'lldb', so: undefined };
     }
   }
 
@@ -106,13 +106,13 @@ function getLib(lldbExe, llvmConfig) {
         'ldd', [lldbExe]
     ).toString().trim();
   } catch (err) {
-    return { dir: undefined, name: 'lldb' };
+    return { dir: undefined, name: 'lldb', so: undefined };
   }
 
   const lib = libs.split(/\s/).find(
       line => line.includes('liblldb') && line.startsWith('/'));
   if (!lib) {
-    return { dir: undefined, name: 'lldb' };
+    return { dir: undefined, name: 'lldb', so: undefined };
   }
 
   console.log(`From ldd: ${lldbExe} loads ${lib}`);
@@ -121,20 +121,22 @@ function getLib(lldbExe, llvmConfig) {
   // On Ubuntu the libraries are suffixed and installed globally
   const libName = path.basename(lib).match(/lib(lldb.*?)\.so/)[1];
 
-  // TODO(joyeecheung): on RedHat there might not be a non-versioned liblldb.so
+  // On RedHat there might not be a non-versioned liblldb.so
   // in the system. It's fine in the case of plugins since the lldb executable
   // will load the library before loading the plugin, but we will have to link
   // to the versioned library file for addons.
-  if (!fs.existsSync(path.join(libDir, `lib${libName}.so`))) {
+  if (fs.existsSync(path.join(libDir, `lib${libName}.so`))) {
     return {
-      dir: undefined,
-      name: libName
+      dir: libDir,
+      name: libName,
+      so: undefined
     };
   }
 
   return {
-    dir: libDir,
-    name: libName
+    dir: undefined,
+    name: libName,
+    so: lib
   };
 }
 
@@ -181,7 +183,9 @@ function getLldbInstallation() {
   const lib = getLib(lldbExe, llvmConfig);
   if (!lib.dir) {
     console.log(`Could not find non-versioned lib${lib.name}.so in the system`);
-    console.log(`Symbols will be resolved by the lldb executable at runtime`);
+    console.log('Plugin symbols will be resolved by the lldb executable ' +
+                'at runtime');
+    console.log(`Addon will be linked to ${lib.so}`);
   } else {
     console.log(`Found lib${lib.name}.so in ${lib.dir}`);
   }
@@ -191,7 +195,8 @@ function getLldbInstallation() {
     version: lldbVersion,
     includeDir: includeDir,
     libDir: lib.dir,
-    libName: lib.name
+    libName: lib.name,
+    libPath: lib.so
   };
 }
 

src/addon.cc

@@ -0,0 +1,13 @@
+#include <nan.h>
+#include "llnode_module.h"
+
+namespace llnode {
+
+NAN_MODULE_INIT(InitAll) {
+  LLNode::Init(target);
+  LLNodeHeapType::Init(target);
+}
+
+NODE_MODULE(addon, InitAll)
+
+}  // namespace llnode