doc, test: doc API design, add tests

PR-URL: #206
Refs: #14
Reviewed-By: Matheus Marchini <[email protected]>

Author: joyeecheung

.travis.yml

@@ -7,26 +7,35 @@ matrix:
       before_install:
         - sudo apt-get -qq update
         - sudo apt-get install lldb-3.9 liblldb-3.9-dev -y
+      install: npm install --llnode_build_addon=true
+      script: TEST_LLDB_BINARY=`which lldb-3.9` npm run test-all
       node_js: "6"
     - sudo: required
       dist: trusty
       before_install:
         - sudo apt-get -qq update
         - sudo apt-get install lldb-3.9 liblldb-3.9-dev -y
+      install: npm install --llnode_build_addon=true
+      script: TEST_LLDB_BINARY=`which lldb-3.9` npm run test-all
       node_js: "8"
     - sudo: required
       dist: trusty
       before_install:
         - sudo apt-get -qq update
         - sudo apt-get install lldb-3.9 liblldb-3.9-dev -y
+      install: npm install --llnode_build_addon=true
+      script: TEST_LLDB_BINARY=`which lldb-3.9` npm run test-all
       node_js: "9"
     - sudo: required
       dist: trusty
       before_install:
         - sudo apt-get -qq update
         - sudo apt-get install lldb-3.9 liblldb-3.9-dev -y
+      install: npm install --llnode_build_addon=true
+      script: TEST_LLDB_BINARY=`which lldb-3.9` npm run test-all
       node_js: "10"
     # Test Node.js master nightly build
+    # Addon is not tested due to lack of node-addon-api
     - node_js: "node"
       sudo: required
       dist: trusty
@@ -35,10 +44,12 @@ matrix:
         - sudo apt-get install lldb-3.9 liblldb-3.9-dev -y
       install:
         - npm install --nodedir=$(dirname $(dirname $(which node)))/include/node
+      script: TEST_LLDB_BINARY=`which lldb-3.9` npm run test-plugin
       env:
         - NVM_NODEJS_ORG_MIRROR=https://nodejs.org/download/nightly
         - NODEJS_ORG_MIRROR=https://nodejs.org/download/nightly
     # Test Node.js v8-canary nightly build
+    # Addon is not tested due to lack of node-addon-api
     - node_js: "node"
       sudo: required
       dist: trusty
@@ -47,21 +58,30 @@ matrix:
         - sudo apt-get install lldb-3.9 liblldb-3.9-dev -y
       install:
         - npm install --nodedir=$(dirname $(dirname $(which node)))/include/node
+      script: TEST_LLDB_BINARY=`which lldb-3.9` npm run test-plugin
       env:
         - NVM_NODEJS_ORG_MIRROR=https://nodejs.org/download/v8-canary
         - NODEJS_ORG_MIRROR=https://nodejs.org/download/v8-canary
     # Test on OS X
     - os: osx
       osx_image: xcode9.3
+      install: npm install --llnode_build_addon=true
+      script: npm run test-all
       node_js: "6"
     - os: osx
       osx_image: xcode9.3
+      install: npm install --llnode_build_addon=true
+      script: npm run test-all
       node_js: "8"
     - os: osx
       osx_image: xcode9.3
+      install: npm install --llnode_build_addon=true
+      script: npm run test-all
       node_js: "9"
     - os: osx
       osx_image: xcode9.3
+      install: npm install --llnode_build_addon=true
+      script: npm run test-all
       node_js: "10"
   allow_failures:
     # Allow the nightly installs to fail
@@ -80,4 +100,3 @@ matrix:
 branches:
   only:
     - master
-script: make _travis

JSAPI.md

@@ -0,0 +1,62 @@
+# Draft of the JavaScript API
+
+This is currently a work in progress, expect the API to change significantly.
+Specifically, the APIs returning strings as results of inspection should return
+structured data instead for ease of use.
+
+```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 {LLNode} llnode
+   * @property {Iterator<HeapInstance>} instances
+   *
+   * @returns {HeapType[]}
+   */
+  getHeapTypes() {}
+
+  /**
+   * TODO: rematerialize object
+   * @returns {HeapInstance}
+   */
+  getObjectAtAddress(address) {}
+}
+```

Makefile

@@ -1,8 +1,7 @@
-TEST_LLDB_BINARY ?= $(shell which lldb-3.9)
-
 .PHONY: all
-all:
-	@echo "Please take a look at README.md"
+all: configure-with-addon
+	node-gyp rebuild
+	node scripts/cleanup.js
 
 .PHONY: install-osx
 install-osx: plugin
@@ -32,20 +31,19 @@ format:
 configure:
 	node scripts/configure.js
 
+.PHONY: configure-with-addon
+configure-with-addon:
+	LLNODE_BUILD_ADDON=true node scripts/configure.js
+
 .PHONY: plugin
 plugin: configure
 	node-gyp rebuild
 	node scripts/cleanup.js
 
 .PHONY: addon
-addon: configure
+addon: configure-with-addon
 	node-gyp rebuild
 
-.PHONY: _travis
-_travis:
-	TEST_LLDB_BINARY="$(TEST_LLDB_BINARY)" \
-	npm test
-
 .PHONY: clean
 clean:
 	$(RM) -r build

README.md

@@ -259,17 +259,28 @@ The easiest way to build the plugin:
 # Clone this repo
 git clone https://github.com/nodejs/llnode.git && cd llnode
 
-# Configure and build the plugin
+# Configure and build the plugin with npm
 npm install
-# Or run
+# To configure and build the plugin without npm
+node scripts/configure.js && node scripts/install.js && node scripts/cleanup.js
+# Or use make
 make plugin
+
+# To configure and build both the plugin and the addon
+npm install --llnode_build_addon=true
+# Without npm
+LLNODE_BUILD_ADDON=true node scripts/configure.js && node scripts/install.js && node scripts/cleanup.js
+# Or use make
+make addon # Builds the addon
+make       # Builds both the addon and the plugin
 ```
 
 To configure the build yourself:
 
 ```bash
 # Detect available lldb installation and download headers if necessary
 node scripts/configure.js
+# To build the addon, set the environment variable LLNODE_BUILD_ADDON=true
 
 # To configure with the detected lldb installation
 node-gyp configure
@@ -280,7 +291,7 @@ node-gyp configure -- -Dlldb_include_dir=/usr/local/Cellar/llvm/5.0.0/include
 # contains `liblldb.so` or `liblldb.dylib`
 node-gyp configure -- -Dlldb_lib_dir=/usr/lib/llvm-3.9/lib
 
-# Build the plugin
+# Build the plugin (and the addon if LLNODE_BUILD_ADDON=true)
 node-gyp build
 
 # Move the built plugin to the project directory
@@ -292,14 +303,16 @@ node scripts/cleanup.js
 To run the tests, if `lldb` is an executable on the `PATH`:
 
 ```bash
-npm run test
+npm run test-all    # Run both addon and plugin tests
+npm run test-plugin # Run plugin tests
+npm run test-addon    # Run addon tests
 ```
 
 If the LLDB executable is named differently, point `TEST_LLDB_BINARY`
-to it:
+to it before running the tests:
 
 ```bash
-TEST_LLDB_BINARY=`which lldb-4.0` npm run test
+TEST_LLDB_BINARY=`which lldb-4.0` npm run test-all
 ```
 
 ### Useful Environment Variables

binding.gyp

@@ -8,7 +8,8 @@
       # 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_so%": ""
+      "lldb_lib_so%": "",
+      "build_addon": "false",
   },
 
   "target_defaults": {
@@ -85,47 +86,53 @@
         ],
       }]
     ]
-  }, {
-    "target_name": "addon",
-    "type": "loadable_module",
-    "include_dirs": [
-      "<!@(node -p \"require('node-addon-api').include\")"
-    ],
-    "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
-    "sources": [
-      "src/addon.cc",
-      "src/llnode_module.cc",
-      "src/llnode_api.cc",
-      "src/constants.cc",
-      "src/error.cc",
-      "src/llv8.cc",
-      "src/llv8-constants.cc",
-      "src/llscan.cc",
-      "src/node-constants.cc",
-    ],
-    "cflags!": [ "-fno-exceptions" ],
-    "cflags_cc!": [ "-fno-exceptions" ],
-    "conditions": [
-      [ "OS=='linux' or OS=='freebsd'", {
+  }],
+
+  "conditions": [
+    [ "build_addon == 'true'", {
+      "targets": [{
+        "target_name": "addon",
+        "type": "loadable_module",
+        "include_dirs": [
+          "<!@(node -p \"require('node-addon-api').include\")"
+        ],
+        "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
+        "sources": [
+          "src/addon.cc",
+          "src/llnode_module.cc",
+          "src/llnode_api.cc",
+          "src/constants.cc",
+          "src/error.cc",
+          "src/llv8.cc",
+          "src/llv8-constants.cc",
+          "src/llscan.cc",
+          "src/node-constants.cc",
+        ],
+        "cflags!": [ "-fno-exceptions" ],
+        "cflags_cc!": [ "-fno-exceptions" ],
         "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)"
+          [ "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)"]
+              }]
             ]
-          }],
-          # 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)"]
           }]
         ]
       }]
-    ]
-  }]
+    }]
+  ]
 }

package.json

@@ -13,7 +13,10 @@
     "preinstall": "node scripts/configure.js",
     "install": "node scripts/install.js",
     "postinstall": "node scripts/cleanup.js",
-    "test": "tape test/*-test.js"
+    "test-plugin": "tape test/plugin/*-test.js",
+    "test-addon": "tape test/addon/*-test.js",
+    "test-all": "npm run test-addon && npm run test-plugin",
+    "test": "npm run test-plugin"
   },
   "repository": {
     "type": "git",

scripts/configure.js

@@ -9,15 +9,27 @@ function main() {
   const buildDir = process.cwd();
   console.log('Build dir is: ' + buildDir);
   const osName = os.type();
-  const result = configureInstallation(osName, buildDir);
-  writeConfig(result.config);
-  writeLlnodeScript(buildDir, result.executable, osName);
+  const { config, executable } = configureInstallation(osName, buildDir);
+  configureBuildOptions(config);
+  writeConfig(config);
+  writeLlnodeScript(buildDir, executable, osName);
   // Exit with success.
   process.exit(0);
 }
 
 main();
 
+// Do not build addon by default until it's less experimental
+function configureBuildOptions(config) {
+  const build_addon = (process.env.npm_config_llnode_build_addon ||
+    process.env.LLNODE_BUILD_ADDON);
+  if (build_addon) {
+    config.variables.build_addon = build_addon;
+  } else {
+    config.variables.build_addon = 'false';
+  }
+}
+
 /**
  * Get and configure the lldb installation. The returned prefix
  * should be linked to ./lldb