Improve N-API support

[jschlight]

I'd like to create a PR to improve support for N-API builds. I'm posting my proposed changes here for review and comment by the community.

Support NAN and N-API builds from the same project

For some projects, it is desirable to build both legacy NAN modules and N-API modules from the same package. In the current node-pre-gyp implementation, if the project specifies one or more N-API builds by including the binary.napi_versions property in the package.json file, and the Node version being built against does not support N-API, node-pre-gyp issues the following error message:

node-pre-gyp ERR! stack Error: The N-API version of this Node instance is undefined. This module supports N-API version(s) 1,3. This Node instance cannot run this module.

The package.json substitution string {node_abi_napi} is intended facilitate NAN and N-API builds from the same project. It can be used to distinguish projects that need this capability.

I propose to modify the current build behavior to attempt a NAN build when all of the following conditions are true:

• The project requests one or more N-API builds by including the binary.napi_versions property in the package.json file.
• The version of Node being built against does not support a sufficient N-API version to create a successful N-API build.
• The binary.package_name property in the package.json file contains the text {node_abi_napi}{napi_build_version}.

The code that attempts downloads would follow the same rules.

For new modules that are designed for N-API only, there is no need to include the {node_abi_napi}{napi_build_version} text. They would not trigger this special rule.

The documentation would also be updated to describe this pattern and its usage.

The C/C++ code would need to determine whether the build being requested is for NAN or N-API. The NAPI_VERSION symbol communicated to the compiler by node-pre-gyp can be used for this purpose.

Verify each napi_build_version against what’s supported by Node

When building for publishing, node-pre-gyp will verify that the build for each N-API version specified in the package.json file is supported by the version of Node being used for the build. If the version is not supported, node-pre-gyp will issue a warning. If no version can be built, node-pre-gyp will issue an error. This will permit add-ons to be tested against older versions of Node that do not support newer N-API versions.

Implement a --build-latest-napi-version-only argument

Implement a new build argument, --build-latest-napi-version-only, that will build only the highest supported N-API version. This will be useful for test builds where only the most current N-API build is of interest by suppressing builds that are eventually ignored.

Improve recovery from build errors

Improve recovery from build errors so that a configure is not required after a build failure.

Documentation update

The current N-API documentation suggests defining the symbol NAPI_BUILD_VERSION for the C/C++ code. The recommended value is NAPI_VERSION and the documentation should be updated to reflect this.

[mhdawson]

I think this would be a good addition.

[jschlight]

@rolftimmermans I am close to submitting a PR. Will you please refresh my memory concerning the circumstances in which a configure is required after a build failure?

[rolftimmermans]

@jschlight I believe in all cases? Without a configure step I receive the following error message after a build fails:

Error: ENOENT: no such file or directory, rename 'build-tmp-napi-v1' -> 'build'

The directory build-tmp-napi-v1 is only correctly recreated after a configure. I'm not sure why it's deleted during build failure, it seems to happen consistently.

Any compiler error (by making a syntax error for example) is enough to trigger it.

[jschlight]

Thank you @rolftimmermans. Got it! It should be fixed in this PR.

[springmeyer]

#405 is merged. @jschlight can this now be closed. #405 will go out in the v0.11.0 release.

[jschlight]

Thank you @springmeyer. I'm available to address any issues that may arise from the PR.

[springmeyer]

Thanks @jschlight - will /cc if I see anything comeup, as will @mapsam who is also looking after this repo.