diff options
author | Michael Dawson <michael_dawson@ca.ibm.com> | 2018-11-14 14:51:12 -0500 |
---|---|---|
committer | Michael Dawson <michael_dawson@ca.ibm.com> | 2018-11-16 17:31:16 -0500 |
commit | a56968698d28325c06f1ad0f0390b10ee218244d (patch) | |
tree | 8e32d4a118df1b18ee6c7e5577c36b319b3e0232 /doc | |
parent | 6b4e413526c4305cd6c604072b8d3066519a549a (diff) | |
download | android-node-v8-a56968698d28325c06f1ad0f0390b10ee218244d.tar.gz android-node-v8-a56968698d28325c06f1ad0f0390b10ee218244d.tar.bz2 android-node-v8-a56968698d28325c06f1ad0f0390b10ee218244d.zip |
doc: better linkage to node-addon-api
One of the comments we got at the N-API workshop
at NodeConfEU was that we should have a better link to
node-addon-api and the docs in the main API docs for
N-API. The goal being to help people find node-addon-api
and potentially start with the node-addon-api docs
instead if they are using C++.
This expands and strengthens the link along with a
recommendation that starting with the node-addon-api
docs might make sense.
PR-URL: https://github.com/nodejs/node/pull/24371
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/n-api.md | 52 |
1 files changed, 45 insertions, 7 deletions
diff --git a/doc/api/n-api.md b/doc/api/n-api.md index c976c5e8f0..27ebefb4b5 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -34,13 +34,51 @@ properties: handling section [Error Handling][]. The N-API is a C API that ensures ABI stability across Node.js versions -and different compiler levels. However, we also understand that a C++ -API can be easier to use in many cases. To support these cases we expect -there to be one or more C++ wrapper modules that provide an inlineable C++ -API. Binaries built with these wrapper modules will depend on the symbols -for the N-API C based functions exported by Node.js. These wrappers are not -part of N-API, nor will they be maintained as part of Node.js. One such -example is: [node-addon-api](https://github.com/nodejs/node-addon-api). +and different compiler levels. A C++ API can be easier to use. +To support using C++, the project maintains a +C++ wrapper module called +[node-addon-api](https://github.com/nodejs/node-addon-api). +This wrapper provides an inlineable C++ API. Binaries built +with `node-addon-api` will depend on the symbols for the N-API C-based +functions exported by Node.js. `node-addon-api` is a more +efficient way to write code that calls N-API. Take, for example, the +following `node-addon-api` code. The first section shows the +`node-addon-api` code and the second section shows what actually gets +used in the addon. + +```C++ +Object obj = Object::New(env); +obj["foo"] = String::New(env, "bar"); +``` + +```C++ +napi_status status; +napi_value object, string; +status = napi_create_object(env, &object); +if (status != napi_ok) { + napi_throw_error(env, ...); + return; +} + +status = napi_crate_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string); +if (status != napi_ok) { + napi_throw_error(env, ...); + return; +} + +status = napi_set_named_property(env, object, "foo", string); +if (status != napi_ok) { + napi_throw_error(env, ...); + return; +} +``` + +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) +for `node-addon-api`. ## Implications of ABI Stability |