n-api,doc: add info about building n-api addons

jschlight · targos · commit ee3c3ad0f56e · 2019-11-11T10:24:52.000+01:00
Adds information about tools available for building N-API addons. Fixes: nodejs/abi-stable-node#384 PR-URL: #30032 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
diff --git 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 <node_api.h>
@@ -5195,3 +5277,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
