Commit 75bf3f4
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -33,23 +33,28 @@ properties: | |||
| 33 | 33 | using `napi_get_last_error_info`. More information can be found in the error | |
| 34 | 34 | handling section [Error handling][]. | |
| 35 | 35 | ||
| 36 | + ## Writing addons in various programming languages | ||
| 37 | + | ||
| 36 | 38 | 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`: | ||
| 47 | 49 | ||
| 48 | 50 | ```cpp | |
| 49 | 51 | Object obj = Object::New(env); | |
| 50 | 52 | obj["foo"] = String::New(env, "bar"); | |
| 51 | 53 | ``` | |
| 52 | 54 | ||
| 55 | + The above `node-addon-api` C++ code is equivalent to the following C-based | ||
| 56 | + Node-API code: | ||
| 57 | + | ||
| 53 | 58 | ```cpp | |
| 54 | 59 | napi_status status; | |
| 55 | 60 | napi_value object, string; | |
@@ -72,8 +77,9 @@ if (status != napi_ok) { | |||
| 72 | 77 | } | |
| 73 | 78 | ``` | |
| 74 | 79 | ||
| 75 | - 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. | ||
| 77 | 83 | ||
| 78 | 84 | When using `node-addon-api` instead of the C APIs, start with the API [docs][] | |
| 79 | 85 | for `node-addon-api`. | |
@@ -6881,6 +6887,7 @@ the add-on's file name during loading. | |||
| 6881 | 6887 | [externals]: #napi_create_external | |
| 6882 | 6888 | [global scope]: globals.md | |
| 6883 | 6889 | [gyp-next]: https://github.com/nodejs/gyp-next | |
| 6890 | + [language and engine bindings]: https://github.com/nodejs/abi-stable-node/blob/doc/node-api-engine-bindings.md | ||
| 6884 | 6891 | [module scope]: modules.md#the-module-scope | |
| 6885 | 6892 | [node-gyp]: https://github.com/nodejs/node-gyp | |
| 6886 | 6893 | [node-pre-gyp]: https://github.com/mapbox/node-pre-gyp | |
0 commit comments