From cb36fa67d77ff6891a48db0b473d1c51888e23ed Mon Sep 17 00:00:00 2001 From: Jim Schlight Date: Fri, 18 Oct 2019 16:03:25 -0700 Subject: [PATCH] n-api,doc: add info about building n-api addons Adds information about tools available for building N-API addons. Fixes: https://github.com/nodejs/abi-stable-node/issues/384 PR-URL: https://github.com/nodejs/node/pull/30032 Reviewed-By: Anna Henningsen Reviewed-By: Gabriel Schulhof Reviewed-By: Luigi Pinca Reviewed-By: Colin Ihrig Reviewed-By: Michael Dawson --- doc/api/n-api.md | 119 +++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 10 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 83a1e98d406f82..d608424c4c7b4c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -14,11 +14,10 @@ changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without recompilation. The [ABI Stability][] guide provides a more in-depth explanation. -Addons are built/packaged with the same approach/tools -outlined in the section titled [C++ Addons](addons.html). -The only difference is the set of APIs that are used by the native code. -Instead of using the V8 or [Native Abstractions for Node.js][] APIs, -the functions available in the N-API are used. +Addons are built/packaged with the same approach/tools outlined in the section +titled [C++ Addons][]. The only difference is the set of APIs that are used by +the native code. Instead of using the V8 or [Native Abstractions for Node.js][] +APIs, the functions available in the N-API are used. APIs exposed by N-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified @@ -76,8 +75,7 @@ if (status != napi_ok) { The end result is that the addon only uses the exported C APIs. As a result, it still gets the benefits of the ABI stability provided by the C API. -When using `node-addon-api` instead of the C APIs, start with the API -[docs](https://github.com/nodejs/node-addon-api#api-documentation) +When using `node-addon-api` instead of the C APIs, start with the API [docs][] for `node-addon-api`. ## Implications of ABI Stability @@ -118,11 +116,95 @@ must make use exclusively of N-API by restricting itself to using and by checking, for all external libraries that it uses, that the external library makes ABI stability guarantees similar to N-API. +## Building + +Unlike modules written in JavaScript, developing and deploying Node.js +native addons using N-API requires an additional set of tools. Besides the +basic tools required to develop for Node.js, the native addon developer +requires a toolchain that can compile C and C++ code into a binary. In +addition, depending upon how the native addon is deployed, the *user* of +the native addon will also need to have a C/C++ toolchain installed. + +For Linux developers, the necessary C/C++ toolchain packages are readily +available. [GCC][] is widely used in the Node.js community to build and +test across a variety of plarforms. For many developers, the [LLVM][] +compiler infrastructure is also a good choice. + +For Mac developers, [Xcode][] offers all the required compiler tools. +However, it is not necessary to install the entire Xcode IDE. The following +command installs the necessary toolchain: + +```bash +xcode-select --install +``` + +For Windows developers, [Visual Studio][] offers all the required compiler +tools. However, it is not necessary to install the entire Visual Studio +IDE. The following command installs the necessary toolchain: + +```bash +npm install --global --production windows-build-tools +``` + +The sections below describe the additional tools available for developing +and deploying Node.js native addons. + +### Build tools + +Both the tools listed here require that *users* of the native +addon have a C/C++ toolchain installed in order to successfully install +the native addon. + +#### node-gyp + +[node-gyp][] is a build system based on Google's [GYP][] tool and comes +bundled with npm. GYP, and therefore node-gyp, requires that Python be +installed. + +Historically, node-gyp has been the tool of choice for building native +addons. It has widespread adoption and documentation. However, some +developers have run into limitations in node-gyp. + +#### CMake.js + +[CMake.js][] is an alternative build system based on [CMake][]. + +CMake.js is a good choice for projects that already use CMake or for +developers affected by limitations in node-gyp. + +### Uploading precompiled binaries + +The three tools listed here permit native addon developers and maintainers +to create and upload binaries to public or private servers. These tools are +typically integrated with CI/CD build systems like [Travis CI][] and +[AppVeyor][] to build and upload binaries for a variety of platforms and +architectures. These binaries are then available for download by users who +do not need to have a C/C++ toolchain installed. + +#### node-pre-gyp + +[node-pre-gyp][] is a tool based on node-gyp that adds the ability to +upload binaries to a server of the developer's choice. node-pre-gyp has +particularly good support for uploading binaries to Amazon S3. + +#### prebuild + +[prebuild][] is a tool that supports builds using either node-gyp or +CMake.js. Unlike node-pre-gyp which supports a variety of servers, prebuild +uploads binaries only to [GitHub releases][]. prebuild is a good choice for +GitHub projects using CMake.js. + +#### prebuildify + +[prebuildify][] is tool based on node-gyp. The advantage of prebuildify is +that the built binaries are bundled with the native module when it's +uploaded to npm. The binaries are downloaded from npm and are immediately +available to the module user when the native module is installed. + ## Usage -In order to use the N-API functions, include the file -[`node_api.h`](https://github.com/nodejs/node/blob/master/src/node_api.h) -which is located in the src directory in the node development tree: +In order to use the N-API functions, include the file [`node_api.h`][] which is +located in the src directory in the node development tree: ```C #include @@ -5222,3 +5304,20 @@ This API may only be called from the main thread. [context-aware addons]: addons.html#addons_context_aware_addons [node-addon-api]: https://github.com/nodejs/node-addon-api [worker threads]: https://nodejs.org/api/worker_threads.html +[C++ Addons]: addons.html +[docs]: https://github.com/nodejs/node-addon-api#api-documentation +[GCC]: https://gcc.gnu.org +[LLVM]: https://llvm.org +[Xcode]: https://developer.apple.com/xcode/ +[Visual Studio]: https://visualstudio.microsoft.com +[node-gyp]: https://github.com/nodejs/node-gyp +[GYP]: https://gyp.gsrc.io +[CMake.js]: https://github.com/cmake-js/cmake-js +[CMake]: https://cmake.org +[Travis CI]: https://travis-ci.org +[AppVeyor]: https://www.appveyor.com +[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp +[prebuild]: https://github.com/prebuild/prebuild +[GitHub releases]: https://help.github.com/en/github/administering-a-repository/about-releases +[prebuildify]: https://github.com/prebuild/prebuildify +[`node_api.h`]: https://github.com/nodejs/node/blob/master/src/node_api.h