node-api: link to other programming language bindings · nodejs/node@99128d9

@@ -33,23 +33,28 @@ properties:

3333

using `napi_get_last_error_info`. More information can be found in the error

3434

handling section [Error handling][].

353536+

## Writing addons in various programming languages

37+3638

Node-API is a C API that ensures ABI stability across Node.js versions

37-

and different compiler levels. A C++ API can be easier to use.

38-

To support using C++, the project maintains a

39-

C++ wrapper module called [`node-addon-api`][].

40-

This wrapper provides an inlinable C++ API. Binaries built

41-

with `node-addon-api` will depend on the symbols for the Node-API C-based

42-

functions exported by Node.js. `node-addon-api` is a more

43-

efficient way to write code that calls Node-API. Take, for example, the

44-

following `node-addon-api` code. The first section shows the

45-

`node-addon-api` code and the second section shows what actually gets

46-

used in the addon.

39+

and different compiler levels. With this stability guarantee, it is possible

40+

to write addons in other programming languages on top of Node-API. Refer

41+

to [language and engine bindings][] for more programming languages and engines

42+

support details.

43+44+

[`node-addon-api`][] is the official C++ binding that provides a more efficient way to

45+

write C++ code that calls Node-API. This wrapper is a header-only library that offers an inlinable C++ API.

46+

Binaries built with `node-addon-api` will depend on the symbols of the Node-API

47+

C-based functions exported by Node.js. The following code snippet is an example

48+

of `node-addon-api`:

47494850

```cpp

4951

Object obj = Object::New(env);

5052

obj["foo"] = String::New(env, "bar");

5153

```

525455+

The above `node-addon-api` C++ code is equivalent to the following C-based

56+

Node-API code:

57+5358

```cpp

5459

napi_status status;

5560

napi_value object, string;

@@ -72,8 +77,9 @@ if (status != napi_ok) {

7277

}

7378

```

747975-

The end result is that the addon only uses the exported C APIs. As a result,

76-

it still gets the benefits of the ABI stability provided by the C API.

80+

The end result is that the addon only uses the exported C APIs. Even though

81+

the addon is written in C++, it still gets the benefits of the ABI stability

82+

provided by the C Node-API.

77837884

When using `node-addon-api` instead of the C APIs, start with the API [docs][]

7985

for `node-addon-api`.

@@ -6887,6 +6893,7 @@ the add-on's file name during loading.

68876893

[externals]: #napi_create_external

68886894

[global scope]: globals.md

68896895

[gyp-next]: https://github.com/nodejs/gyp-next

6896+

[language and engine bindings]: https://github.com/nodejs/abi-stable-node/blob/doc/node-api-engine-bindings.md

68906897

[module scope]: modules.md#the-module-scope

68916898

[node-gyp]: https://github.com/nodejs/node-gyp

68926899

[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp