Skip to content

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

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

Closed
jschlight wants to merge 4 commits into from
Closed

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

Changes from 1 commit
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
Prev Previous commit
n-api,doc: add info about building n-api addons
  • Loading branch information
@jschlight
jschlight committed Oct 25, 2019
commit fcb25972f4fa68a5f4eb9bff0e2dc745ea69354e
110 changes: 59 additions & 51 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 @@ -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
Expand All @@ -159,60 +157,54 @@ 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
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.

Comment thread
jschlight marked this conversation as 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 @@ -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