Install now keeps all binaries; chooose at runtime

Author: cjbj

.npmignore

@@ -6,7 +6,7 @@ INSTALL.md
 CONTRIBUTING.md
 Makefile
 binding.gyp
-oracledb-*.tgz
+*.tgz
 /doc
 /examples
 /test
@@ -26,8 +26,8 @@ oracledb-*.tgz
 /build/gyp-mac-tool
 /node_modules
 /oracle_private
-/package/build.js
-/package/buildv6binary.js
+/package/buildbinary.js
+/package/buildpackage.js
 /package/Staging
 /odpi
 /src

CHANGELOG.md

@@ -56,9 +56,12 @@ This release is currently under development.
   String limited to the VARCHAR2 length.
 
 - Update install processes by bundling all pre-built binaries into the
-  package uploaded to https://www.npmjs.com/package/oracledb.  This
-  removes the need for the installer to download a binary package from
-  GitHub.  Also, source code is no longer included in the npm package.
+  https://www.npmjs.com/package/oracledb package, removing the need
+  for a separate binary package download from GitHub.  At runtime an
+  appropriate binary is loaded by `require()`, if it exists, allowing
+  one `node_modules/oracledb` install to be usable in different
+  environments.  Also, source code is no longer included in the npm
+  package.
 
 - Fixed a crash with high frequency notifications from CQN
   ([#1009](https://github.com/oracle/node-oracledb/issues/1009)).

INSTALL.md

@@ -41,7 +41,7 @@ limitations under the License.
     - 3.11 [Node-oracledb Installation Without Internet Access](#offline)
         - 3.11.1 [Copying node-oracledb Binaries on Windows](#winbins)
     - 3.12 [Installing Node.js and Node-oracledb RPMs from yum.oracle.com](#instnoderpms)
-    - 3.13 [Hosting your own node-oracledb Packages](#selfhost)
+    - 3.13 [Building and Hosting your own node-oracledb Packages](#selfhost)
 4. [Installing Node-oracledb 1.x or 2.x](#installingoldvers)
 5. [Useful Resources for Node-oracledb](#otherresources)
 6. [Troubleshooting Node-oracledb Installation Problems](#troubleshooting)
@@ -69,8 +69,10 @@ guaranteed to be available or usable in your environment.
 #### <a name="mig31"></a> 1.1 Changes in node-oracledb version 3.1
 
 Pre-built binaries are now contained in the package downloaded from
-npm.  This removes the internally executed step of downloading a
-binary package from GitHub.
+npm.  This removes the previous internally executed step of
+downloading a suitable binary package from GitHub.  If install size is
+an issue, all binaries except those for the current Node.js version
+can be deleted with `npm run prune`.
 
 Source code is no longer included in the package available from npm.
 To compile from source code, you need access to GitHub or its [Oracle
@@ -315,8 +317,7 @@ included in Node.js:
 npm install oracledb
 ```
 
-Available pre-built node-oracledb binaries can been seen on the
-[releases][41] page.  They were built on Oracle Linux 6.
+The pre-built binaries were built on Oracle Linux 6.
 
 If a pre-built binary is successfully installed but isn't usable
 because it depends on a different glibc version, uninstall
@@ -458,8 +459,7 @@ included in Node.js:
 npm install oracledb
 ```
 
-Available pre-built node-oracledb binaries can been seen on the
-[releases][41] page.  They were built on Oracle Linux 6.
+The pre-built binaries were built on Oracle Linux 6.
 
 If a pre-built binary is successfully installed but isn't usable
 because it depends on a different glibc version, uninstall
@@ -595,9 +595,6 @@ included in Node.js:
 npm install oracledb
 ```
 
-Available pre-built node-oracledb binaries can been seen on the
-[releases][41] page.
-
 If a pre-built binary is successfully installed but isn't usable
 because it depends on a different glibc version, uninstall
 node-oracledb and install again from source code.
@@ -695,9 +692,6 @@ included in Node.js:
 npm install oracledb
 ```
 
-Available pre-built node-oracledb binaries can been seen on the
-[releases][41] page.
-
 ##### To install from source code:
 
 If a pre-built node-oracledb binary is not installable, the binary can
@@ -819,9 +813,6 @@ included in Node.js:
 npm install oracledb
 ```
 
-Available pre-built node-oracledb binaries can been seen on the
-[releases][41] page.
-
 ##### To install from source code:
 
 If a pre-built node-oracledb binary is not installable, the binary can
@@ -919,7 +910,7 @@ client installation.  Make sure that `PATH` contains the correct
 binary directory, for example `C:\oracle\product\12.2.0\dbhome_1\bin`.
 
 For easy development, the free [Oracle XE][20] version of the database
-is available on Linux.  Applications developed with XE may be
+is available on Windows.  Applications developed with XE may be
 immediately used with other editions of the Oracle Database.
 
 You may need Administrator privileges to set environment variables or
@@ -952,9 +943,6 @@ included in Node.js:
 npm install oracledb
 ```
 
-Available pre-built node-oracledb binaries can been seen on the
-[releases][41] page.
-
 ##### To install from source code:
 
 If a pre-built node-oracledb binary is not installable, the binary can
@@ -1427,7 +1415,7 @@ export NODE_PATH=$(npm root -g)
 node myapp.js
 ```
 
-### <a name="selfhost"></a> 3.13 Hosting your own node-oracledb Packages
+### <a name="selfhost"></a> 3.13 Building and Hosting your own node-oracledb Packages
 
 You can host node-oracledb packages locally.
 
@@ -1440,9 +1428,9 @@ can be used.  See
 [package/README](https://github.com/oracle/node-oracledb/blob/master/package/README.md)
 for details.
 
-If you make the package accessible on your local machine, for example
-at https://www.example.com/oracledb-3.1.0.tgz, then your install
-command would be:
+If you make the package accessible on your local web server, for
+example at https://www.example.com/oracledb-3.1.0.tgz, then your
+install command would be:
 
 ```
 npm install https://www.example.com/oracledb-3.1.0.tgz

lib/oracledb.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2015, 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -30,44 +30,39 @@ var getConnectionPromisified;
 var poolCache = {};
 var tempUsedPoolAliases = {};
 var defaultPoolAlias = 'default';
-var binaryReleasePath = '../build/Release/oracledb.node';
-var binaryDebugPath = '../build/Debug/oracledb.node';
-
-// Load the node-oracledb binary add-on that was built when 'npm
-// install' invoked node-gyp.
-// The Debug version of node-oracledb will only exist if 'npm install
-// --debug oracledb' was used.  Typically only the maintainers of
-// node-oracledb do this.
-try {
-  oracledbCLib =  require(binaryReleasePath);
-} catch (err) {
-  var nodeInfo = process.versions.node + ' (' + process.platform + ', ' + process.arch +')\n';
-  var fullReleasePath = require('path').resolve(__dirname, binaryReleasePath);
-  if (err.code === 'MODULE_NOT_FOUND') {
-    try {
-      oracledbCLib = require(binaryDebugPath);
-    } catch (err) {
+
+//  Load the Oracledb binary
+
+var binaryLocations = [
+  '../' + nodbUtil.RELEASE_DIR + '/' + nodbUtil.BINARY_FILE,  // pre-built binary
+  '../' + nodbUtil.RELEASE_DIR + '/' + 'oracledb.node',       // binary built from source
+  '../build/Debug/oracledb.node'                              // debug binary
+];
+
+for (var i = 0; i < binaryLocations.length; i++) {
+  try {
+    oracledbCLib = require(binaryLocations[i]);
+    break;
+  } catch(err) {
+    if (err.code !== 'MODULE_NOT_FOUND' || i == binaryLocations.length - 1) {
+      var nodeInfo;
       if (err.code === 'MODULE_NOT_FOUND') {
-        // Neither Release or Debug binary was found but assume users wanted Release binary
-        nodeInfo += 'Cannot find module ' + fullReleasePath + '\n' + nodbUtil.getInstallHelp();
-        throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
+        // none of the three binaries could be found
+        nodeInfo = `\n  Looked for ${binaryLocations.map(x => require('path').resolve(__dirname, x)).join(', ')}\n  ${nodbUtil.getInstallURL()}\n`;
       } else {
-        nodeInfo += 'Cannot load ' + binaryDebugPath + '\n';
-        nodeInfo += 'Node.js require() error was: \n  ' + err.message + '\n' + nodbUtil.getInstallHelp();
-        throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
+        nodeInfo = `\n  Node.js require('oracledb') error was:\n  ${err.message}\n  ${nodbUtil.getInstallHelp()}\n`;
       }
+      throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
     }
-  } else {
-    nodeInfo += 'Cannot load ' + fullReleasePath + '\n' + err.message + '\n' + nodbUtil.getInstallHelp();
-    throw new Error(nodbUtil.getErrorMessage('NJS-045', nodeInfo));
   }
 }
 
+// Oracledb functions and classes
+
 oracledbCLib.Oracledb.prototype.newLob = function(iLob) {
   return new Lob(iLob, null, oracledbInst);
 };
 
-
 // This createPool function is used the override the createPool method of the
 // Oracledb class, which is defined in the C layer. The override allows us to do
 // things like extend out the pool instance prior to passing it to the caller.

lib/util.js

@@ -1,4 +1,4 @@
-/* Copyright (c) 2016, 2018, Oracle and/or its affiliates. All rights reserved. */
+/* Copyright (c) 2016, 2019, Oracle and/or its affiliates. All rights reserved. */
 
 /******************************************************************************
  *
@@ -21,6 +21,18 @@
 
 var util = require('util');
 
+// Directory containing the node-oracledb add-on binary
+const RELEASE_DIR = 'build/Release';
+module.exports.RELEASE_DIR = RELEASE_DIR;
+
+// The default node-oracledb add-on binary filename for this Node.js
+const BINARY_FILE = 'oracledb-abi' + process.versions.modules + '-' + process.platform + '-' + process.arch + '.node';
+module.exports.BINARY_FILE = BINARY_FILE;
+
+// Staging directory used by maintainers building the npm package
+const STAGING_DIR = 'package/Staging';
+module.exports.STAGING_DIR = STAGING_DIR;
+
 var EventEmitter = require('events').EventEmitter;
 var eventEmitterKeys = Object.keys(EventEmitter.prototype);
 var eventEmitterFuncKeys = eventEmitterKeys.filter(function(key) {
@@ -40,7 +52,7 @@ var errorMessages = {
   'NJS-041': 'NJS-041: cannot convert ResultSet to QueryStream after invoking methods',
   'NJS-042': 'NJS-042: cannot invoke ResultSet methods after converting to QueryStream',
   'NJS-043': 'NJS-043: ResultSet already converted to QueryStream',
-  'NJS-045': 'NJS-045: cannot load the oracledb add-on binary for Node.js %s',
+  'NJS-045': 'NJS-045: cannot load a node-oracledb binary for Node.js ' + process.versions.node + ' (' + process.platform + ' ' + process.arch + ') %s',
   'NJS-046': 'NJS-046: poolAlias "%s" already exists in the connection pool cache',
   'NJS-047': 'NJS-047: poolAlias "%s" not found in the connection pool cache',
   'NJS-054': 'NJS-054: binary build/Release/oracledb.node was not installed',
@@ -49,11 +61,17 @@ var errorMessages = {
   'NJS-067': 'NJS-067: a pre-built node-oracledb binary was not found for Node.js %s'
 };
 
+// getInstallURL returns a string with installation URL
+function getInstallURL() {
+  return('Node-oracledb installation instructions: https://oracle.github.io/node-oracledb/INSTALL.html');
+}
+
+module.exports.getInstallURL = getInstallURL;
+
 // getInstallHelp returns a string with installation usage tips that may be helpful
 function getInstallHelp() {
-  var arch, url, mesg = '';
-  mesg = 'Node-oracledb installation instructions: ';
-  mesg += 'https://oracle.github.io/node-oracledb/INSTALL.html\n';
+  var arch, url;
+  var mesg = getInstallURL() + '\n';
   if (process.platform === 'linux') {
     if (process.arch === 'x64') {
       url = 'http://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html\n';

package.json

@@ -39,7 +39,9 @@
   "scripts": {
     "testv6": "mocha --opts test/opts/mochaNodeV6.opts",
     "test": "mocha --opts test/opts/mocha.opts",
-    "posttest": "node test/opts/version.js"
+    "posttest": "node test/opts/version.js",
+    "buildbinary": "node package/buildbinary.js",
+    "buildpackage": "node package/buildpackage.js"
   },
   "engines": {
     "node": ">=6"

package/README.md

@@ -1,34 +1,46 @@
 # Overview
 
-This directory is used for building the node-oracledb npm package.
+This directory is used for building the [node-oracledb npm
+package](https://www.npmjs.com/package/oracledb).  The scripts can
+also be used to create custom packages for hosting on a local server.
+
 Most users do not need to use anything in this directory.
 
 # Maintainers
 
-- The file `build.js` is used by node-oracledb maintainers to create
-  node-oracledb binaries and the package to be uploaded to
-  [npm](https://www.npmjs.com/package/oracledb).
+In a clone or copy of the repository:
 
-- `node build.js binary` creates a binary for the current Node.js /
-  node-oracledb / platform combination.  The command `node
-  buildv6binary.js` can be used with Node 6.
+- `npm run buildbinary` calls `buildbinary.js` to create a binary for
+  the current node-oracledb / Node.js / platform combination.
 
-- `node build.js package` makes the node-oracledb package containing
-  the node-oracledb JavaScript files, the binaries, and a package.json
-  that has an "install" script.
+- `npm run buildpackage` calls `buildpackage.js` to make the
+  node-oracledb package containing the node-oracledb JavaScript files,
+  the available binaries, and a package.json that has an "install"
+  script and a "prune" script.  The package will be created in the top
+  level directory.
 
-  Before running this, all binaries and related build metadata
-  information files from all Node.js / node-oracledb / platform
-  combinations should be placed in the `package/Staging` directory.
+  Before executing `npm run buildpackage`, all binaries and related
+  build metadata information files from all node-oracledb / Node.js /
+  platform combinations should be placed in the `package/Staging`
+  directory.
 
-- As part of `npm install oracledb`, the `package.json` install script
-  invokes `package/install.js` to move the appropriate binary module
-  to the correct directory.
+Package installation:
 
-  If a suitable binary is not available, installation will fail.
-  Users must then compile node-oracledb using source code from GitHub.
+- As part of an `npm install` that uses the created package, the
+  `package.json` install script runs `package/install.js` to check a
+  binary module for the current Node.js and platform is available.
 
-- By default `../package.json` doesn't have an install script target.
-  This means that node-gyp will be invoked to compile node-oracledb.
-  This allows installation from source code (via GitHub) when no
-  suitable pre-built binary is available.
+  If a suitable binary is not available, installation will fail.
+  Users must then compile node-oracledb using source code from GitHub,
+  or choose an alternative Node.js / platform that has a pre-built
+  binary module.
+
+- After install, space conscious users can run `npm run prune` which
+  removes pre-built binaries for all other Node.js releases and
+  architectures.
+
+By default the top level `package.json` doesn't have an install script
+target.  This means that node-gyp will be invoked to compile
+node-oracledb.  This allows installation from [source
+code](https://oracle.github.io/node-oracledb/INSTALL.html#github) (via
+GitHub) when no suitable pre-built binary is available.