Skip to content

Commit 5543c01

Browse files
Nicola Del Gobbomhdawson
Nicola Del Gobbo
authored and
mhdawson
committedNov 23, 2017
doc: add more content to documentation
PR-URL: #192 Reviewed-By: Michael Dawson <[email protected]>
·
v8.3.11.6.0
1 parent 74de0cb commit 5543c01

33 files changed

+286
-11
lines changed
 

‎README.md

+20-3
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,11 @@ values. Concepts and operations generally map to ideas specified in the
2626
- **[Examples](#examples)**
2727
- **[Tests](#tests)**
2828
- **[More resource and info about native Addons](#resources)**
29+
- **[Code of Conduct](CODE_OF_CONDUCT.md)**
2930
- **[Contributors](#contributors)**
3031
- **[License](#license)**
3132

32-
## **Current version: 1.0.0**
33+
## **Current version: 1.1.0**
3334

3435
(See [CHANHELOG.md](CHANGELOG.md) for complete Changelog)
3536

@@ -84,13 +85,29 @@ values. Concepts and operations generally map to ideas specified in the
8485

8586
### **Examples**
8687

87-
//TODO References to examples
88+
Are you new to **N-API**? Take a look at our **[examples](https://github.com/nodejs/abi-stable-node-addon-examples)**
89+
90+
- **[Hello World](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/1_hello_world/node-addon-api)**
91+
- **[Pass arguments to a function](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/2_function_arguments/node-addon-api)**
92+
- **[Callbacks](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/3_callbacks/node-addon-api)**
93+
- **[Object factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)**
94+
- **[Function factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)**
95+
- **[Wrapping C++ Object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/6_object_wrap/node-addon-api)**
96+
- **[Factory of wrapped object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/7_factory_wrap/node-addon-api)**
97+
- **[Passing wrapped object around](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/8_passing_wrapped/node-addon-api)**
8898

8999
<a name="tests"></a>
90100

91101
### **Tests**
92102

93-
//TODO References to tests
103+
To run the **N-API** tests do:
104+
105+
```
106+
npm install
107+
npm test
108+
```
109+
110+
Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/master/test)**
94111

95112
<a name="resources"></a>
96113

‎doc/array.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Array
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/array_buffer.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Array buffer
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/async_operations.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Asynchronous operations
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/async_worker.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Async worker
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/basic_types.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Basic Types
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/boolean.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Boolean
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/buffer.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Buffer
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/class_property_descriptor.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Class propertry and descriptior
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/cmake-js.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# CMake.js
2+
3+
**CMake.js** is a build tool that allow native addon developer to compile their
4+
C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
5+
instead of Google's **gyp** format it is base on **CMake** build system.
6+
7+
## **CMake** reference
8+
9+
- [Installation](https://www.npmjs.com/package/cmake-js#installation)
10+
- [How to use](https://www.npmjs.com/package/cmake-js#usage)
11+
- [Tutorials](https://www.npmjs.com/package/cmake-js#tutorials)
12+
- [Use case in the works - ArrayFire.js](https://www.npmjs.com/package/cmake-js#use-case-in-the-works---arrayfirejs)
13+
14+
Sometimes finding the right settings is not easy so to accomplish at most
15+
complicated task please refer to:
16+
17+
- [CMake documentation](https://cmake.org/)
18+
- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)

‎doc/conversion-tool.md

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
1-
## Conversion Tool
1+
# Conversion Tool
22

3-
To make the migration to node-addon-api easier, we have provided a script to help
4-
complete the steps listed above. To use the conversion script:
3+
To make the migration to **node-addon-api** easier, we have provided a script to
4+
help complete some tasks.
5+
6+
## To use the conversion script:
57

68
1. Go to your module directory
79

@@ -14,15 +16,13 @@ cd [module_path]
1416
```
1517
npm install node-addon-api
1618
```
17-
1819
3. Run node-addon-api conversion script
1920

2021
```
2122
node ./node_modules/node-addon-api/tools/conversion.js ./
2223
```
2324

2425
4. While this script makes conversion easier, it still cannot fully convert
25-
2626
the module. The next step is to try to build the module and complete the
2727
remaining conversions necessary to allow it to compile and pass all of the
2828
module's tests.

‎doc/error.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Error
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/error_handling.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Error handling
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/escapable_handle_sope.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Escapable handle scope
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/function.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Function
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/function_reference.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Function reference
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/generator.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Generator
2+
3+
## What is generator
4+
5+
**[generator-napi-module](https://www.npmjs.com/package/generator-napi-module)** is a module to quickly generate a skeleton module using
6+
**N-API**, the new API for Native addons. This module automatically sets up your
7+
**gyp file** to use **node-addon-api**, the C++ wrappers for N-API and generates
8+
a wrapper JS module. Optionally, it can even configure the generated project to
9+
use **TypeScript** instead.
10+
11+
## **generator-napi-module** reference
12+
13+
- [Installation and usage](https://www.npmjs.com/package/generator-napi-module#installation)

‎doc/handle_scope.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Handle scope
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/name.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Name
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/node-gyp.md

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# node-gyp
2+
3+
C++ code needs to be compiled into executable form whether it be as an object
4+
file to linked with others, a shared library, or a standalone executable.
5+
6+
The main reason for this is that we need to link to the Node.js dependencies and
7+
headers correcrtly, another reason is that we need a cross platform way to build
8+
C++ soucre into binary for the target platform,
9+
10+
Until now **node-gyp** is the **de-fafto** standard build tool for writing
11+
Node.js addons. It's based on Google's **gyp** build tool, which abstract away
12+
many of the tedious issues related to cross platform building.
13+
14+
**node-gyp** uses a file called ```binding.gyp``` that is located on the root of
15+
your addon project.
16+
17+
```binding.gyp``` file, contains all building configurations organized with a
18+
JSON like syntax. The most important parameter is the **target** that must be
19+
set to the same value used on the initialization code of the addon as in the
20+
examples reported below:
21+
22+
### **binding.gyp**
23+
24+
```gyp
25+
{
26+
"targets": [
27+
{
28+
# myModule is the name of your native addon
29+
"target_name": "myModule",
30+
"sources": ["src/my_module.cc", ...],
31+
...
32+
]
33+
}
34+
```
35+
36+
### **my_module.cc**
37+
38+
```cpp
39+
#include <napi.h>
40+
41+
// ...
42+
43+
/**
44+
* This code is our entry-point. We receive two arguments here, the first is the
45+
* environment that represent an independent instance of the JavaScript runtime,
46+
* the second is exports, the same as module.exports in a .js file.
47+
* You can either add properties to the exports object passed in or create your
48+
* own exports object. In either case you must return the object to be used as
49+
* the exports for the module when you return from the Init function.
50+
*/
51+
Napi::Object Init(Napi::Env env, Napi::Object exports) {
52+
53+
// ...
54+
55+
return exports;
56+
}
57+
58+
/**
59+
* This code defines the entry-point for the Node addon, it tells Node where to go
60+
* once the library has been loaded into active memory. The first argument must
61+
* match the "target" in our *binding.gyp*. The second argument points to the
62+
* function to invoke.
63+
*/
64+
NODE_API_MODULE(myModule, Init)
65+
```
66+
67+
## **node-gyp** reference
68+
69+
- [Installation](https://www.npmjs.com/package/node-gyp#installation)
70+
- [How to use](https://www.npmjs.com/package/node-gyp#how-to-use)
71+
- [The binding.gyp file](https://www.npmjs.com/package/node-gyp#the-bindinggyp-file)
72+
- [Commands](https://www.npmjs.com/package/node-gyp#commands)
73+
- [Command options](https://www.npmjs.com/package/node-gyp#command-options)
74+
- [Configuration](https://www.npmjs.com/package/node-gyp#configuration)
75+
76+
Sometimes finding the right settings for ```binding.gyp``` is not easy so to
77+
accomplish at most complicated task please refer to:
78+
79+
- [GYP documentation](https://gyp.gsrc.io/index.md)
80+
- [node-gyp wiki](https://github.com/nodejs/node-gyp/wiki)

‎doc/object.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Object
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/object_reference.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Object reference
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/object_wrap.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -6,4 +6,8 @@ JavaScript code to a C++ object.
66
Classes extending ```ObjectWrap``` can be instantiated from JavaScript using the
77
**new** operator, and their methods can be directly invoked from JavaScript.
88
The **wrap** word refers to a way to group methods and state of your class because it
9-
will be your responsibility write custom code to bridge each of your C++ class methods.
9+
will be your responsibility write custom code to bridge each of your C++ class methods.
10+
11+
You are reading a draft of the next documentation and it's in continuos update so
12+
if you don't find what you need please refer to:
13+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/onject_lifetime_management.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Object lifetime management
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/promises.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Promise
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/property_descriptor.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# property descriptor
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/reference.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Reference
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/setup.md

+15-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,19 @@
1-
## Setup
1+
# Setup
22

3-
To use N-API in a native module:
3+
## Prerequisites
4+
5+
Before starting to use **N-API** you need to assure you have the following
6+
prerequisites:
7+
8+
* **Node.JS** see: [Installing Node.js](https://nodejs.org/)
9+
10+
* **Node.js native addon build tool**
11+
12+
- **[node-gyp](node-gyp.md)**
13+
14+
## Installation and usage
15+
16+
To use **N-API** in a native module:
417

518
1. Add a dependency on this package to `package.json`:
619

‎doc/string.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# String
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/symbol.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Symbol
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/typed_array.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Typed array
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/typed_array_of.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Typed array of
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

‎doc/working_with_javascript_values.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Working with JavaScript Values
2+
3+
You are reading a draft of the next documentation and it's in continuos update so
4+
if you don't find what you need please refer to:
5+
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)

0 commit comments

Comments
 (0)
Please sign in to comment.