From d5ffcd92cabba67d51bc573ddbd029db1e5700cd Mon Sep 17 00:00:00 2001 From: Kenvin Davies Date: Thu, 23 Nov 2017 20:25:20 +0100 Subject: [PATCH] doc: add more content to documentation PR-URL: https://github.com/nodejs/node-addon-api/pull/192 Reviewed-By: Michael Dawson --- README.md | 23 +++++++- doc/array.md | 5 ++ doc/array_buffer.md | 5 ++ doc/async_operations.md | 5 ++ doc/async_worker.md | 5 ++ doc/basic_types.md | 5 ++ doc/boolean.md | 5 ++ doc/buffer.md | 5 ++ doc/class_property_descriptor.md | 5 ++ doc/cmake-js.md | 18 ++++++ doc/conversion-tool.md | 10 ++-- doc/error.md | 5 ++ doc/error_handling.md | 5 ++ doc/escapable_handle_sope.md | 5 ++ doc/function.md | 5 ++ doc/function_reference.md | 5 ++ doc/generator.md | 13 +++++ doc/handle_scope.md | 5 ++ doc/name.md | 5 ++ doc/node-gyp.md | 80 +++++++++++++++++++++++++++ doc/object.md | 5 ++ doc/object_reference.md | 5 ++ doc/object_wrap.md | 6 +- doc/onject_lifetime_management.md | 5 ++ doc/promises.md | 5 ++ doc/property_descriptor.md | 5 ++ doc/reference.md | 5 ++ doc/setup.md | 17 +++++- doc/string.md | 5 ++ doc/symbol.md | 5 ++ doc/typed_array.md | 5 ++ doc/typed_array_of.md | 5 ++ doc/working_with_javascript_values.md | 5 ++ 33 files changed, 286 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 83663ec..3282d04 100644 --- a/README.md +++ b/README.md @@ -26,10 +26,11 @@ values. Concepts and operations generally map to ideas specified in the - **[Examples](#examples)** - **[Tests](#tests)** - **[More resource and info about native Addons](#resources)** +- **[Code of Conduct](CODE_OF_CONDUCT.md)** - **[Contributors](#contributors)** - **[License](#license)** -## **Current version: 1.0.0** +## **Current version: 1.1.0** (See [CHANHELOG.md](CHANGELOG.md) for complete Changelog) @@ -84,13 +85,29 @@ values. Concepts and operations generally map to ideas specified in the ### **Examples** -//TODO References to examples +Are you new to **N-API**? Take a look at our **[examples](https://github.com/nodejs/abi-stable-node-addon-examples)** + +- **[Hello World](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/1_hello_world/node-addon-api)** +- **[Pass arguments to a function](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/2_function_arguments/node-addon-api)** +- **[Callbacks](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/3_callbacks/node-addon-api)** +- **[Object factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)** +- **[Function factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)** +- **[Wrapping C++ Object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/6_object_wrap/node-addon-api)** +- **[Factory of wrapped object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/7_factory_wrap/node-addon-api)** +- **[Passing wrapped object around](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/8_passing_wrapped/node-addon-api)** ### **Tests** -//TODO References to tests +To run the **N-API** tests do: + +``` +npm install +npm test +``` + +Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/master/test)** diff --git a/doc/array.md b/doc/array.md index e69de29..613bb66 100644 --- a/doc/array.md +++ b/doc/array.md @@ -0,0 +1,5 @@ +# Array + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/array_buffer.md b/doc/array_buffer.md index e69de29..58031a6 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -0,0 +1,5 @@ +# Array buffer + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) diff --git a/doc/async_operations.md b/doc/async_operations.md index e69de29..438312a 100644 --- a/doc/async_operations.md +++ b/doc/async_operations.md @@ -0,0 +1,5 @@ +# Asynchronous operations + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/async_worker.md b/doc/async_worker.md index e69de29..a50f6f7 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -0,0 +1,5 @@ +# Async worker + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/basic_types.md b/doc/basic_types.md index e69de29..e3a94ac 100644 --- a/doc/basic_types.md +++ b/doc/basic_types.md @@ -0,0 +1,5 @@ +# Basic Types + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/boolean.md b/doc/boolean.md index e69de29..355b209 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -0,0 +1,5 @@ +# Boolean + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/buffer.md b/doc/buffer.md index e69de29..3412b3b 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -0,0 +1,5 @@ +# Buffer + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/class_property_descriptor.md b/doc/class_property_descriptor.md index e69de29..43f8f20 100644 --- a/doc/class_property_descriptor.md +++ b/doc/class_property_descriptor.md @@ -0,0 +1,5 @@ +# Class propertry and descriptior + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/cmake-js.md b/doc/cmake-js.md index e69de29..39b952d 100644 --- a/doc/cmake-js.md +++ b/doc/cmake-js.md @@ -0,0 +1,18 @@ +# CMake.js + +**CMake.js** is a build tool that allow native addon developer to compile their +C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but +instead of Google's **gyp** format it is base on **CMake** build system. + +## **CMake** reference + + - [Installation](https://www.npmjs.com/package/cmake-js#installation) + - [How to use](https://www.npmjs.com/package/cmake-js#usage) + - [Tutorials](https://www.npmjs.com/package/cmake-js#tutorials) + - [Use case in the works - ArrayFire.js](https://www.npmjs.com/package/cmake-js#use-case-in-the-works---arrayfirejs) + +Sometimes finding the right settings is not easy so to accomplish at most +complicated task please refer to: + +- [CMake documentation](https://cmake.org/) +- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki) \ No newline at end of file diff --git a/doc/conversion-tool.md b/doc/conversion-tool.md index d0e05dc..3b50b9c 100644 --- a/doc/conversion-tool.md +++ b/doc/conversion-tool.md @@ -1,7 +1,9 @@ -## Conversion Tool +# Conversion Tool -To make the migration to node-addon-api easier, we have provided a script to help -complete the steps listed above. To use the conversion script: +To make the migration to **node-addon-api** easier, we have provided a script to +help complete some tasks. + +## To use the conversion script: 1. Go to your module directory @@ -14,7 +16,6 @@ cd [module_path] ``` npm install node-addon-api ``` - 3. Run node-addon-api conversion script ``` @@ -22,7 +23,6 @@ node ./node_modules/node-addon-api/tools/conversion.js ./ ``` 4. While this script makes conversion easier, it still cannot fully convert - the module. The next step is to try to build the module and complete the remaining conversions necessary to allow it to compile and pass all of the module's tests. \ No newline at end of file diff --git a/doc/error.md b/doc/error.md index e69de29..5ad6bef 100644 --- a/doc/error.md +++ b/doc/error.md @@ -0,0 +1,5 @@ +# Error + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/error_handling.md b/doc/error_handling.md index e69de29..14c0c4a 100644 --- a/doc/error_handling.md +++ b/doc/error_handling.md @@ -0,0 +1,5 @@ +# Error handling + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/escapable_handle_sope.md b/doc/escapable_handle_sope.md index e69de29..37d6ddd 100644 --- a/doc/escapable_handle_sope.md +++ b/doc/escapable_handle_sope.md @@ -0,0 +1,5 @@ +# Escapable handle scope + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/function.md b/doc/function.md index e69de29..4b60785 100644 --- a/doc/function.md +++ b/doc/function.md @@ -0,0 +1,5 @@ +# Function + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/function_reference.md b/doc/function_reference.md index e69de29..1ffe8dd 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -0,0 +1,5 @@ +# Function reference + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/generator.md b/doc/generator.md index e69de29..9167480 100644 --- a/doc/generator.md +++ b/doc/generator.md @@ -0,0 +1,13 @@ +# Generator + +## What is generator + +**[generator-napi-module](https://www.npmjs.com/package/generator-napi-module)** is a module to quickly generate a skeleton module using +**N-API**, the new API for Native addons. This module automatically sets up your +**gyp file** to use **node-addon-api**, the C++ wrappers for N-API and generates +a wrapper JS module. Optionally, it can even configure the generated project to +use **TypeScript** instead. + +## **generator-napi-module** reference + + - [Installation and usage](https://www.npmjs.com/package/generator-napi-module#installation) diff --git a/doc/handle_scope.md b/doc/handle_scope.md index e69de29..2bf03be 100644 --- a/doc/handle_scope.md +++ b/doc/handle_scope.md @@ -0,0 +1,5 @@ +# Handle scope + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/name.md b/doc/name.md index e69de29..9549d71 100644 --- a/doc/name.md +++ b/doc/name.md @@ -0,0 +1,5 @@ +# Name + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/node-gyp.md b/doc/node-gyp.md index e69de29..3100698 100644 --- a/doc/node-gyp.md +++ b/doc/node-gyp.md @@ -0,0 +1,80 @@ +# node-gyp + +C++ code needs to be compiled into executable form whether it be as an object +file to linked with others, a shared library, or a standalone executable. + +The main reason for this is that we need to link to the Node.js dependencies and +headers correcrtly, another reason is that we need a cross platform way to build +C++ soucre into binary for the target platform, + +Until now **node-gyp** is the **de-fafto** standard build tool for writing +Node.js addons. It's based on Google's **gyp** build tool, which abstract away +many of the tedious issues related to cross platform building. + +**node-gyp** uses a file called ```binding.gyp``` that is located on the root of +your addon project. + +```binding.gyp``` file, contains all building configurations organized with a +JSON like syntax. The most important parameter is the **target** that must be +set to the same value used on the initialization code of the addon as in the +examples reported below: + +### **binding.gyp** + +```gyp +{ + "targets": [ + { + # myModule is the name of your native addon + "target_name": "myModule", + "sources": ["src/my_module.cc", ...], + ... + ] +} +``` + +### **my_module.cc** + +```cpp +#include + +// ... + +/** +* This code is our entry-point. We receive two arguments here, the first is the +* environment that represent an independent instance of the JavaScript runtime, +* the second is exports, the same as module.exports in a .js file. +* You can either add properties to the exports object passed in or create your +* own exports object. In either case you must return the object to be used as +* the exports for the module when you return from the Init function. +*/ +Napi::Object Init(Napi::Env env, Napi::Object exports) { + + // ... + + return exports; +} + +/** +* This code defines the entry-point for the Node addon, it tells Node where to go +* once the library has been loaded into active memory. The first argument must +* match the "target" in our *binding.gyp*. The second argument points to the +* function to invoke. +*/ +NODE_API_MODULE(myModule, Init) +``` + +## **node-gyp** reference + + - [Installation](https://www.npmjs.com/package/node-gyp#installation) + - [How to use](https://www.npmjs.com/package/node-gyp#how-to-use) + - [The binding.gyp file](https://www.npmjs.com/package/node-gyp#the-bindinggyp-file) + - [Commands](https://www.npmjs.com/package/node-gyp#commands) + - [Command options](https://www.npmjs.com/package/node-gyp#command-options) + - [Configuration](https://www.npmjs.com/package/node-gyp#configuration) + +Sometimes finding the right settings for ```binding.gyp``` is not easy so to +accomplish at most complicated task please refer to: + +- [GYP documentation](https://gyp.gsrc.io/index.md) +- [node-gyp wiki](https://github.com/nodejs/node-gyp/wiki) diff --git a/doc/object.md b/doc/object.md index e69de29..1f46ace 100644 --- a/doc/object.md +++ b/doc/object.md @@ -0,0 +1,5 @@ +# Object + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/object_reference.md b/doc/object_reference.md index e69de29..2d80341 100644 --- a/doc/object_reference.md +++ b/doc/object_reference.md @@ -0,0 +1,5 @@ +# Object reference + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/object_wrap.md b/doc/object_wrap.md index fc79dbf..d2349f0 100644 --- a/doc/object_wrap.md +++ b/doc/object_wrap.md @@ -6,4 +6,8 @@ JavaScript code to a C++ object. Classes extending ```ObjectWrap``` can be instantiated from JavaScript using the **new** operator, and their methods can be directly invoked from JavaScript. The **wrap** word refers to a way to group methods and state of your class because it -will be your responsibility write custom code to bridge each of your C++ class methods. \ No newline at end of file +will be your responsibility write custom code to bridge each of your C++ class methods. + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/onject_lifetime_management.md b/doc/onject_lifetime_management.md index e69de29..cf9d2a2 100644 --- a/doc/onject_lifetime_management.md +++ b/doc/onject_lifetime_management.md @@ -0,0 +1,5 @@ +# Object lifetime management + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/promises.md b/doc/promises.md index e69de29..34c56a9 100644 --- a/doc/promises.md +++ b/doc/promises.md @@ -0,0 +1,5 @@ +# Promise + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md index e69de29..bb49e17 100644 --- a/doc/property_descriptor.md +++ b/doc/property_descriptor.md @@ -0,0 +1,5 @@ +# property descriptor + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/reference.md b/doc/reference.md index e69de29..bd78a7c 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -0,0 +1,5 @@ +# Reference + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/setup.md b/doc/setup.md index f8136fc..84dafd3 100644 --- a/doc/setup.md +++ b/doc/setup.md @@ -1,6 +1,19 @@ -## Setup +# Setup -To use N-API in a native module: +## Prerequisites + +Before starting to use **N-API** you need to assure you have the following +prerequisites: + +* **Node.JS** see: [Installing Node.js](https://nodejs.org/) + +* **Node.js native addon build tool** + + - **[node-gyp](node-gyp.md)** + +## Installation and usage + +To use **N-API** in a native module: 1. Add a dependency on this package to `package.json`: diff --git a/doc/string.md b/doc/string.md index e69de29..5987356 100644 --- a/doc/string.md +++ b/doc/string.md @@ -0,0 +1,5 @@ +# String + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/symbol.md b/doc/symbol.md index e69de29..ab4b36e 100644 --- a/doc/symbol.md +++ b/doc/symbol.md @@ -0,0 +1,5 @@ +# Symbol + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/typed_array.md b/doc/typed_array.md index e69de29..cc33682 100644 --- a/doc/typed_array.md +++ b/doc/typed_array.md @@ -0,0 +1,5 @@ +# Typed array + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md index e69de29..c87f281 100644 --- a/doc/typed_array_of.md +++ b/doc/typed_array_of.md @@ -0,0 +1,5 @@ +# Typed array of + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file diff --git a/doc/working_with_javascript_values.md b/doc/working_with_javascript_values.md index e69de29..e15f7c7 100644 --- a/doc/working_with_javascript_values.md +++ b/doc/working_with_javascript_values.md @@ -0,0 +1,5 @@ +# Working with JavaScript Values + +You are reading a draft of the next documentation and it's in continuos update so +if you don't find what you need please refer to: +[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) \ No newline at end of file