Discussion about the next steps

[NickNaso]

In this issue I reported some correlated issues some of them pushed us to work on this repo:

• Calling napi_ functions from MinGW-compiled addon results in access violation Calling napi_ functions from MinGW-compiled addon results in access violation node#38782
• undefined reference linking errors during cross-compilation (using cmake-js) undefined reference linking errors during cross-compilation (using cmake-js) node-addon-api#1021
• why the src/node_api.h and node_api_types.h head files were moved to the node repository why the src/node_api.h and node_api_types.h head files were moved to the node repository node-addon-api#855
• Provide definition files for stable API symbol exports Provide definition files for stable API symbol exports node-addon-api#720

My idea is to continue to work on documentation and then publish on npm.

[mhdawson]

+1

[Julusian]

@NickNaso Thank you for creating this!

I stumbled upon this by accident, while in the middle of overhauling some of the internals of cmake-js. This is a much nicer method than having to download the headers for some arbitrary version of nodejs.

With a bit of work, I even managed to avoid needing to source a copy of node.lib. Using the symbols information it is possible to generate a compatible version without much difficulty.

This removes all the downloads that cmake-js used to perform during a build targetting node-api. It also makes me happier about the safety of using node-api as the non node-api headers are no longer available to be included accidentally.

[NickNaso]

Hi @Julusian,
I like to hear your feedback. We created node-api-headers to allow the build of native addon without download all the headers for a specific version of Node.js. This is possible because Node-API is an ABI stable API and it's independent from any Node.js version what matters is the version of Node-API.

Node-API has some experimental API that are not part of any version because they are not considered stable. We removed from the headers the features e / o functions that are under NAPI_EXPERIMENTAL so this means that if a developer set the NAPI_EXPERIMENTAL flag he will obtain a compilation error.

I don't know if this could be a problem, but I want to discuss at the next Node-API meeting https://github.com/nodejs/abi-stable-node#meeting. If you have time and want to join us it will be a pleasure to discuss about this together.

My idea is to use the original Node-API's headers (without removing the experimental feature) and add a new section named EXPERIMENTAL in the symbol.js like reported below:

    EXPERIMENTAL: {
        js_native_api_symbols: [
            // List of symbols in js_native_api.h considered experimental.
        ],
        node_api_symbols: [
          // List of symbols in node_api.h considered experimental.
        ]
    }