Skip to content

Commit

Permalink
n-api,doc: add info about building n-api addons
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
@jschlight @targos
jschlight authored and targos committed Oct 28, 2019
1 parent 1d9f427 commit 93b1bb8
Showing 1 changed file with 109 additions and 10 deletions.
119 changes: 109 additions & 10 deletions doc/api/n-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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

0 comments on commit 93b1bb8

Please sign in to comment.