Discussion about the next steps

NickNaso commented 2 years ago

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 https://github.com/nodejs/node/issues/38782
undefined reference linking errors during cross-compilation (using cmake-js) https://github.com/nodejs/node-addon-api/issues/1021
why the src/node_api.h and node_api_types.h head files were moved to the node repository https://github.com/nodejs/node-addon-api/issues/855
Provide definition files for stable API symbol exports https://github.com/nodejs/node-addon-api/issues/720

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

mhdawson commented 2 years ago

+1

Julusian commented 2 years ago

@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 commented 2 years ago

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.
        ]
    }

nodejs / node-api-headers

Discussion about the next steps #3