Node-API add-on build about abi-stable-node HOT 4 OPEN

Since the content of EXPERIMENTAL can change there is not guarrantee that any build made with EXPERIMENTAL will work with the latest version (the APIs can be removed or modified while experimental). I think it's safer to not include them in the separate headers but if we do documentation should make it clear that anything that uses that option make break with any future version.

from abi-stable-node.

I'll reply to nodejs/node-api-headers#3 (comment) over here, as it feels like a better place to continue discussion

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

At this stage, the experimental apis are not something I have thought about, so I dont have any insight on how I think they should be handled.
My main focus has been on wrapping native libraries as npm packages (https://www.npmjs.com/package/@julusian/jpeg-turbo, https://www.npmjs.com/package/node-hid, https://www.npmjs.com/package/freetype2), so I've typically been targetting an older node-api version, and have not considered using anything from experimental.

That said, if someone does want to use experimental with cmake-js v7, I will need to do something to allow them to. But that might be best achieved by letting them use the old flow of downloading a specific version of the nodejs headers and building against that. That flow wont be removed anytime soon, as it is still necessary for non node-api projects.

from abi-stable-node.

We discussed in the 10 Jun Node API meeting to include the experimental APIs under a new EXPERIMENTAL property like @NickNaso suggested in #438 (comment) . This property will include all of the previous version's symbols as well, since someone using experimental APIs would only target the most recent Node API version. It doesn't make sense to target a previous version and still use experimental APIs, since those APIs would never be included in the previous version.

from abi-stable-node.

Proposal to sue node-api-headers in node-gyp nodejs/node-gyp#2736

from abi-stable-node.