From 882be6de6be39d5f094024963f1f8d7376443fa4 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Tue, 18 Sep 2018 11:02:04 -0400 Subject: [PATCH 1/3] tools: add tool to check for N-API modules Adds tools/check-napi.js which uses `nm -a` on UNIX and `dumpbin /imports` on Windows to check whether a given `.node` file is an N-API module or not. Intentionally ignores files named `nothing.node` because they are node-addon-api build artefacts. Sets the target type for `nothing` (which gets built when a built-in N-API is found to be present) to `'static_library'` so as to avoid the creation of `nothing.node` files which incorrectly end up showing up in the output of `check-napi.js` as non-N-API modules. --- tools/check-napi.js | 96 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 tools/check-napi.js diff --git a/tools/check-napi.js b/tools/check-napi.js new file mode 100644 index 000000000..e33398ccf --- /dev/null +++ b/tools/check-napi.js @@ -0,0 +1,96 @@ +// Descend into a directory structure and, for each file matching *.node, output +// based on the imports found in the file whether it's an N-API module or not. + +const fs = require('fs'); +const path = require('path'); +const child_process = require('child_process'); + +// Read the output of the command, break it into lines, and use the reducer to +// decide whether the file is an N-API module or not. +function checkFile(file, command, arguments, reducer) { + const child = child_process.spawn(command, arguments, { + stdio: ['inherit', 'pipe', 'inherit'] + }); + let leftover = ''; + let isNapi = undefined; + child.stdout.on('data', (chunk) => { + if (isNapi === undefined) { + chunk = leftover + chunk.toString(); + const haveLeftover = !!chunk.match(/[\r\n]+$/); + chunk = chunk.split(/[\r\n]+/); + leftover = chunk.pop(); + isNapi = chunk.reduce(reducer, isNapi); + } + }); + child.on('exit', (code, signal) => { + if ((code === null && signal !== null) || (code !== 0)) { + console.log( + command + ' exited with code: ' + code + ' and signal: ' + signal); + } else { + console.log( + '\033[' + (isNapi ? '42' : '41') + 'm' + + (isNapi ? ' N-API' : 'Not N-API') + + '\033[0m: ' + file); + } + }); +} + +// Use nm -a to list symbols. +function checkFileUNIX(file) { + checkFile(file, 'nm', ['-a', file], (soFar, line) => { + if (soFar === undefined) { + line = line.match(/([0-9a-f]*)? ([a-zA-Z]) (.*$)/); + line.shift(); + if (line[1] === 'U') { + if (line[2].match(/^napi/)) { + soFar = true; + } + } + } + return soFar; + }); +} + +// Use dumpbin /imports to list symbols. +function checkFileWin32(file) { + checkFile(file, 'dumpbin', ['/imports', file], (soFar, line) => { + if (soFar === undefined) { + line = line.match(/([0-9a-f]*)? +([a-zA-Z0-9]) (.*$)/); + if (line && line[line.length - 1].match(/^napi/)) { + soFar = true; + } + } + return soFar; + }); +} + +// Descend into a directory structure and pass each file ending in '.node' to +// one of the above checks, depending on the OS. +function recurse(top) { + fs.readdir(top, (error, items) => { + items.forEach((item) => { + item = path.join(top, item); + fs.stat(item, ((item) => (error, stats) => { + if (!error) { + if (stats.isDirectory()) { + recurse(item); + } else if (item.match(/[.]node$/) && + // Explicitly ignore files called 'nothing.node' because they are + // artefacts of node-addon-api having identified a version of + // Node.js that ships with a correct implementation of N-API. + path.basename(item) !== 'nothing.node') { + process.platform === 'win32' ? + checkFileWin32(item) : + checkFileUNIX(item); + } + } else { + throw ("error about " + item + ": " + error); + } + })(item)); + }); + }); +} + +// Start with the directory given on the command line or the current directory +// if nothing was given. +recurse(process.argv.length > 3 ? process.argv[2] : '.'); From 9c81e5feca283d46bb6b29a2f00e049d375a2733 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Wed, 19 Sep 2018 09:33:42 -0400 Subject: [PATCH 2/3] squash! address review comments --- tools/check-napi.js | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/tools/check-napi.js b/tools/check-napi.js index e33398ccf..8bf2b830a 100644 --- a/tools/check-napi.js +++ b/tools/check-napi.js @@ -15,14 +15,15 @@ function checkFile(file, command, arguments, reducer) { let isNapi = undefined; child.stdout.on('data', (chunk) => { if (isNapi === undefined) { - chunk = leftover + chunk.toString(); - const haveLeftover = !!chunk.match(/[\r\n]+$/); - chunk = chunk.split(/[\r\n]+/); + chunk = (leftover + chunk.toString()).split(/[\r\n]+/); leftover = chunk.pop(); isNapi = chunk.reduce(reducer, isNapi); + if (isNapi !== undefined) { + child.kill(); + } } }); - child.on('exit', (code, signal) => { + child.on('close', (code, signal) => { if ((code === null && signal !== null) || (code !== 0)) { console.log( command + ' exited with code: ' + code + ' and signal: ' + signal); @@ -40,9 +41,8 @@ function checkFileUNIX(file) { checkFile(file, 'nm', ['-a', file], (soFar, line) => { if (soFar === undefined) { line = line.match(/([0-9a-f]*)? ([a-zA-Z]) (.*$)/); - line.shift(); - if (line[1] === 'U') { - if (line[2].match(/^napi/)) { + if (line[2] === 'U') { + if (/^napi/.test(line[3])) { soFar = true; } } @@ -56,7 +56,7 @@ function checkFileWin32(file) { checkFile(file, 'dumpbin', ['/imports', file], (soFar, line) => { if (soFar === undefined) { line = line.match(/([0-9a-f]*)? +([a-zA-Z0-9]) (.*$)/); - if (line && line[line.length - 1].match(/^napi/)) { + if (line && /^napi/.test(line[line.length - 1])) { soFar = true; } } @@ -74,7 +74,7 @@ function recurse(top) { if (!error) { if (stats.isDirectory()) { recurse(item); - } else if (item.match(/[.]node$/) && + } else if (/[.]node$/.test(item) && // Explicitly ignore files called 'nothing.node' because they are // artefacts of node-addon-api having identified a version of // Node.js that ships with a correct implementation of N-API. From 63193525c65e9eeafd6684cad78b46bcf7ee73fe Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Thu, 20 Sep 2018 19:07:09 -0400 Subject: [PATCH 3/3] squash! add doc and address nits --- README.md | 1 + doc/checker-tool.md | 32 +++++++++++++++++++++++ tools/check-napi.js | 64 ++++++++++++++++++++++++--------------------- 3 files changed, 67 insertions(+), 30 deletions(-) create mode 100644 doc/checker-tool.md diff --git a/README.md b/README.md index 9d4011575..e9aafb753 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,7 @@ to ideas specified in the **ECMA262 Language Specification**. - [node-gyp](doc/node-gyp.md) - [cmake-js](doc/cmake-js.md) - [Conversion tool](doc/conversion-tool.md) + - [Checker tool](doc/checker-tool.md) - [Generator](doc/generator.md) diff --git a/doc/checker-tool.md b/doc/checker-tool.md new file mode 100644 index 000000000..499d3ab9d --- /dev/null +++ b/doc/checker-tool.md @@ -0,0 +1,32 @@ +# Checker Tool + +**node-addon-api** provides a [checker tool][] that will inspect a given +directory tree, identifying all Node.js native addons therein, and further +indicating for each addon whether it is an N-API addon. + +## To use the checker tool: + + 1. Install the application with `npm install`. + + 2. If the application does not depend on **node-addon-api**, copy the + checker tool into the application's directory. + + 3. If the application does not depend on **node-addon-api**, run the checker + tool from the application's directory: + + ```sh + node ./check-napi.js + ``` + + Otherwise, the checker tool can be run from the application's + `node_modules/` subdirectory: + + ```sh + node ./node_modules/node-addon-api/tools/check-napi.js + ``` + +The tool accepts the root directory from which to start checking for Node.js +native addons as a single optional command line parameter. If ommitted it will +start checking from the current directory (`.`). + +[checker tool]: ../tools/check-napi.js diff --git a/tools/check-napi.js b/tools/check-napi.js index 8bf2b830a..48fdfc077 100644 --- a/tools/check-napi.js +++ b/tools/check-napi.js @@ -1,3 +1,4 @@ +'use strict'; // Descend into a directory structure and, for each file matching *.node, output // based on the imports found in the file whether it's an N-API module or not. @@ -7,8 +8,8 @@ const child_process = require('child_process'); // Read the output of the command, break it into lines, and use the reducer to // decide whether the file is an N-API module or not. -function checkFile(file, command, arguments, reducer) { - const child = child_process.spawn(command, arguments, { +function checkFile(file, command, argv, reducer) { + const child = child_process.spawn(command, argv, { stdio: ['inherit', 'pipe', 'inherit'] }); let leftover = ''; @@ -28,10 +29,11 @@ function checkFile(file, command, arguments, reducer) { console.log( command + ' exited with code: ' + code + ' and signal: ' + signal); } else { + // Green if it's a N-API module, red otherwise. console.log( - '\033[' + (isNapi ? '42' : '41') + 'm' + + '\x1b[' + (isNapi ? '42' : '41') + 'm' + (isNapi ? ' N-API' : 'Not N-API') + - '\033[0m: ' + file); + '\x1b[0m: ' + file); } }); } @@ -39,28 +41,28 @@ function checkFile(file, command, arguments, reducer) { // Use nm -a to list symbols. function checkFileUNIX(file) { checkFile(file, 'nm', ['-a', file], (soFar, line) => { - if (soFar === undefined) { - line = line.match(/([0-9a-f]*)? ([a-zA-Z]) (.*$)/); - if (line[2] === 'U') { - if (/^napi/.test(line[3])) { - soFar = true; - } + if (soFar === undefined) { + line = line.match(/([0-9a-f]*)? ([a-zA-Z]) (.*$)/); + if (line[2] === 'U') { + if (/^napi/.test(line[3])) { + soFar = true; } } - return soFar; + } + return soFar; }); } // Use dumpbin /imports to list symbols. function checkFileWin32(file) { checkFile(file, 'dumpbin', ['/imports', file], (soFar, line) => { - if (soFar === undefined) { - line = line.match(/([0-9a-f]*)? +([a-zA-Z0-9]) (.*$)/); - if (line && /^napi/.test(line[line.length - 1])) { - soFar = true; - } + if (soFar === undefined) { + line = line.match(/([0-9a-f]*)? +([a-zA-Z0-9]) (.*$)/); + if (line && /^napi/.test(line[line.length - 1])) { + soFar = true; } - return soFar; + } + return soFar; }); } @@ -68,24 +70,26 @@ function checkFileWin32(file) { // one of the above checks, depending on the OS. function recurse(top) { fs.readdir(top, (error, items) => { + if (error) { + throw ("error reading directory " + top + ": " + error); + } items.forEach((item) => { item = path.join(top, item); fs.stat(item, ((item) => (error, stats) => { - if (!error) { - if (stats.isDirectory()) { - recurse(item); - } else if (/[.]node$/.test(item) && - // Explicitly ignore files called 'nothing.node' because they are - // artefacts of node-addon-api having identified a version of - // Node.js that ships with a correct implementation of N-API. - path.basename(item) !== 'nothing.node') { - process.platform === 'win32' ? - checkFileWin32(item) : - checkFileUNIX(item); - } - } else { + if (error) { throw ("error about " + item + ": " + error); } + if (stats.isDirectory()) { + recurse(item); + } else if (/[.]node$/.test(item) && + // Explicitly ignore files called 'nothing.node' because they are + // artefacts of node-addon-api having identified a version of + // Node.js that ships with a correct implementation of N-API. + path.basename(item) !== 'nothing.node') { + process.platform === 'win32' ? + checkFileWin32(item) : + checkFileUNIX(item); + } })(item)); }); });