Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
wants to merge 4 commits into from
Closed

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

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3628b0c
n-api,doc: add info about building n-api addons
jschlight Oct 18, 2019
e897d3e
n-api,doc: add info about building n-api addons
jschlight Oct 19, 2019
139313c
n-api,doc: add info about building n-api addons
jschlight Oct 24, 2019
fcb2597
n-api,doc: add info about building n-api addons
jschlight Oct 25, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 109 additions & 10 deletions doc/api/n-api.md
View file
Open in desktop
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.

jschlight marked this conversation as resolved.
Show resolved Hide resolved
## 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