build: introduce include_dir

Introduce `include_dir` for use with gyp in a scalar context

Deprecate use of `include` in an gyp array context, which
happens to work when paths are absolute, but can fail on Windows
when paths are relative and a gyp file contains multiple entries
in its `include_dirs` directive.

This change corrects documentation and tooling, adds support for
relative paths (e.g. those containing whitespace) in a backwards
compatible manner and makes the approach holistically consistent
with that used by nan.

PR-URL: #766
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

common.gypi

@@ -15,7 +15,7 @@
       }
     }]
   ],
-  'include_dirs': ["<!@(node -p \"require('../').include\")"],
+  'include_dirs': ["<!(node -p \"require('../').include_dir\")"],
   'cflags': [ '-Werror', '-Wall', '-Wextra', '-Wpedantic', '-Wunused-parameter' ],
   'cflags_cc': [ '-Werror', '-Wall', '-Wextra', '-Wpedantic', '-Wunused-parameter' ]
 }

doc/setup.md

@@ -26,7 +26,7 @@ To use **N-API** in a native module:
   2. Reference this package's include directory and gyp file in `binding.gyp`:
 
 ```gyp
-  'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
+  'include_dirs': ["<!(node -p \"require('node-addon-api').include_dir\")"],
 ```
 
   3. Decide whether the package will enable C++ exceptions in the N-API wrapper.

index.js

@@ -1,10 +1,11 @@
 const path = require('path');
 
-const include = path.relative('.', __dirname);
+const include_dir = path.relative('.', __dirname);
 
 module.exports = {
-  include: include,
-  gyp: path.join(include, 'node_api.gyp:nothing'),
+  include: `"${__dirname}"`, // deprecated, can be removed as part of 4.0.0
+  include_dir,
+  gyp: path.join(include_dir, 'node_api.gyp:nothing'),
   isNodeApiBuiltin: true,
   needsFlag: false
 };

tools/conversion.js

@@ -22,8 +22,8 @@ if (disable != "--disable" && dir != "--disable") {
        [ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ]
     ],
     'binding.gyp': [
-       [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!@(node -p "require(\\\'node-addon-api\\\').include")\',' ],
-       [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!@(node -p \\"require(\'node-addon-api\').include\\")",' ],
+       [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!(node -p "require(\\\'node-addon-api\\\').include_dir")\',' ],
+       [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!(node -p \\"require(\'node-addon-api\').include_dir\\")",' ],
        [ /[ ]*("|')<!\(node -e ("|'|\\"|\\')require\(("|'|\\"|\\')nan("|'|\\"|\\')\)("|'|\\"|\\')\)("|')(,|)[\r\n]/g, '' ],
        [ /([ ]*)("|')target_name("|'): ("|')(.+?)("|'),/g, '$1$2target_name$2: $4$5$6,\n      $2cflags!$2: [ $2-fno-exceptions$2 ],\n      $2cflags_cc!$2: [ $2-fno-exceptions$2 ],\n      $2xcode_settings$2: { $2GCC_ENABLE_CPP_EXCEPTIONS$2: $2YES$2,\n        $2CLANG_CXX_LIBRARY$2: $2libc++$2,\n        $2MACOSX_DEPLOYMENT_TARGET$2: $210.7$2,\n      },\n      $2msvs_settings$2: {\n        $2VCCLCompilerTool$2: { $2ExceptionHandling$2: 1 },\n      },' ],
     ]
@@ -35,8 +35,8 @@ if (disable != "--disable" && dir != "--disable") {
       [ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ]
     ],
     'binding.gyp': [
-      [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!@(node -p "require(\\\'node-addon-api\\\').include")\',' ],
-      [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!@(node -p \'require(\\\"node-addon-api\\\").include\')",' ],
+      [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!(node -p "require(\\\'node-addon-api\\\').include_dir")\',' ],
+      [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!(node -p \'require(\\\"node-addon-api\\\").include_dir\')",' ],
       [ /[ ]*("|')<!\(node -e ("|'|\\"|\\')require\(("|'|\\"|\\')nan("|'|\\"|\\')\)("|'|\\"|\\')\)("|')(,|)[\r\n]/g, '' ],
       [ /([ ]*)("|')target_name("|'): ("|')(.+?)("|'),/g, '$1$2target_name$2: $4$5$6,\n      $2cflags!$2: [ $2-fno-exceptions$2 ],\n      $2cflags_cc!$2: [ $2-fno-exceptions$2 ],\n      $2defines$2: [ $2NAPI_DISABLE_CPP_EXCEPTIONS$2 ],\n      $2conditions$2: [\n        [\'OS==\"win\"\', { $2defines$2: [ $2_HAS_EXCEPTIONS=1$2 ] }]\n      ]' ],
     ]