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

doc/api/n-api.md

@@ -118,6 +118,96 @@ 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. 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
+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.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](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. It has widespread adoption and documentation. However, some
+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 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.
+
+#### 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][]. 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
 
 In order to use the N-API functions, include the file
@@ -5222,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