From 3628b0c25cf01d56fc681198268a960da8c03d68 Mon Sep 17 00:00:00 2001 From: Jim Schlight Date: Fri, 18 Oct 2019 16:03:25 -0700 Subject: [PATCH 1/4] 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 --- doc/api/n-api.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index ff430941778ff0..5cac3a52d49161 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -118,6 +118,89 @@ 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 addons coded in JavaScript, developing and deploying Node native +addons using N-API requires an additional set of tools. Besides the basic +tools required to develop for Node, 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 is typically already +installed. For systems lacking the necessary toolchain, the +[LLVM](https://llvm.org) compiler infrastructure is a good choice. + +For Mac developers, [Xcode](https://developer.apple.com/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](https://visualstudio.microsoft.com) +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 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](https://github.com/nodejs/node-gyp) is a build system based on +Google's [GYP](https://gyp.gsrc.io) 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. However, Google has stopped development on GYP and some developers +are concerned about the dependency of some GYP versions on Python 2.7 which +has a sunset date of 2020. + +#### CMake.js + +[CMake.js](https://github.com/cmake-js/cmake-js) is an alternative build +system based on [CMake](https://cmake.org). + +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 two 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](https://travis-ci.org) and [AppVeyor](https://www.appveyor.com) +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](https://github.com/mapbox/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](https://github.com/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](https://github.com/prebuild/prebuild). prebuild is a +good choice for GitHub projects using CMake.js. + ## Usage In order to use the N-API functions, include the file From e897d3e2ab586c023be00d49a673961646777cac Mon Sep 17 00:00:00 2001 From: Jim Schlight Date: Sat, 19 Oct 2019 10:33:03 -0700 Subject: [PATCH 2/4] n-api,doc: add info about building n-api addons --- doc/api/n-api.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 5cac3a52d49161..e7f8be4d94191b 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -120,16 +120,16 @@ library makes ABI stability guarantees similar to N-API. ## Building -Unlike addons coded in JavaScript, developing and deploying Node native +Unlike modules written in JavaScript, developing and deploying Node native addons using N-API requires an additional set of tools. Besides the basic -tools required to develop for Node, the native addon developer requires a +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 is typically already -installed. For systems lacking the necessary toolchain, the -[LLVM](https://llvm.org) compiler infrastructure is a good choice. +For Linux developers, the necessary C/C++ toolchain packages are readily +available. For many developers, the [LLVM](https://llvm.org) compiler +infrastructure is a good choice. For Mac developers, [Xcode](https://developer.apple.com/xcode/) offers all the required compiler tools. However, it is not necessary to install the @@ -164,9 +164,8 @@ Google's [GYP](https://gyp.gsrc.io) 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. However, Google has stopped development on GYP and some developers -are concerned about the dependency of some GYP versions on Python 2.7 which -has a sunset date of 2020. +addons. It has widespread adoption and documentation. However, some +developers have run into limitations in node-gyp. #### CMake.js From 139313c420a28937a7b7c1d7fdc48a55e74fab53 Mon Sep 17 00:00:00 2001 From: Jim Schlight Date: Thu, 24 Oct 2019 14:16:00 -0700 Subject: [PATCH 3/4] n-api,doc: add info about building n-api addons --- doc/api/n-api.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index e7f8be4d94191b..8db93bb81d1ca7 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -120,7 +120,7 @@ library makes ABI stability guarantees similar to N-API. ## Building -Unlike modules written in JavaScript, developing and deploying Node native +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, @@ -149,13 +149,13 @@ npm install --global --production windows-build-tools ``` The sections below describe the additional tools available for developing -and deploying Node native addons. +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. +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 @@ -177,7 +177,7 @@ developers affected by limitations in node-gyp. ### Uploading precompiled binaries -The two tools listed here permit native addon developers and maintainers to +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](https://travis-ci.org) and [AppVeyor](https://www.appveyor.com) @@ -197,8 +197,16 @@ uploading binaries to Amazon S3. [prebuild](https://github.com/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](https://github.com/prebuild/prebuild). prebuild is a -good choice for GitHub projects using CMake.js. +[GitHub releases][]. prebuild is a good choice for GitHub projects using +CMake.js. + +#### prebuildify + +[prebuildify](https://github.com/prebuild/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 @@ -5304,3 +5312,4 @@ 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 +[GitHub releases]: https://help.github.com/en/github/administering-a-repository/about-releases From fcb25972f4fa68a5f4eb9bff0e2dc745ea69354e Mon Sep 17 00:00:00 2001 From: Jim Schlight Date: Fri, 25 Oct 2019 13:05:01 -0700 Subject: [PATCH 4/4] n-api,doc: add info about building n-api addons --- doc/api/n-api.md | 110 +++++++++++++++++++++++++---------------------- 1 file changed, 59 insertions(+), 51 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 8db93bb81d1ca7..47b76e1c4e4aa3 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 @@ -120,29 +118,29 @@ 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. +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. For many developers, the [LLVM](https://llvm.org) compiler -infrastructure is a good choice. +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](https://developer.apple.com/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: +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](https://visualstudio.microsoft.com) -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: +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 @@ -159,9 +157,9 @@ the native addon. #### node-gyp -[node-gyp](https://github.com/nodejs/node-gyp) is a build system based on -Google's [GYP](https://gyp.gsrc.io) tool and comes bundled with npm. GYP, -and therefore node-gyp, requires that Python be installed. +[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 @@ -169,50 +167,44 @@ developers have run into limitations in node-gyp. #### CMake.js -[CMake.js](https://github.com/cmake-js/cmake-js) is an alternative build -system based on [CMake](https://cmake.org). +[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](https://travis-ci.org) and [AppVeyor](https://www.appveyor.com) -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. +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](https://github.com/mapbox/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. +[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](https://github.com/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. +[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](https://github.com/prebuild/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. +[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 @@ -5312,4 +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