electron
/
addon-tools-el
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 Update docs and version for v2.0.0 release

This commit is contained in:
raub 2018-05-14 11:11:11 +03:00
parent 0a8b92893b
commit 4b642f6a2d
2 changed files with 163 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
README.md
View File

@ -47,32 +47,63 @@ Useful links: [V8 Ref](https://v8docs.nodesource.com/node-0.8/d2/dc3/namespacev8
### binding.gyp ### binding.gyp
* Crossplatform commands can be put into the variables for later use. <details>
``` <summary>Crossplatform commands</summary>
'variables': {
```
'variables': {
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")', 'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")', 'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")',
'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")', 'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")',
}, },
``` ```
* Include directories for Addon Tools and Nan (which is preinstalled with Addon Tools) On both Windows and Unix those are the console commands for various
are accessible as shown below. file system operations. No need for GYP conditions, yay!
``` </details>
'include_dirs': [
'<!@(node -e "require(\'addon-tools-raub\').include()")',
],
```
* Intermediate build-files can be removed in a separate build-step with `<(rm)`.
<details> <details>
<summary>Show Snippet</summary> <summary>Addon binary directory</summary>
``` ```
'variables': {
'binary' : '<!(node -e "require(\'addon-tools-raub\').bin()")',
},
```
In some cases, you'd like to have your addon installed for multiple architectures
simultaneously. For example, when using NVM to fluently switch environments.
Because the target directory is different for each arch, you only have to do
`npm rebuild` after the first switch.
</details>
<details>
<summary>Include directories</summary>
```
'include_dirs': [
'<!@(node -e "require(\'addon-tools-raub\').include()")',
],
```
Those are the directory paths to C++ include files for Addon Tools and Nan
(which is preinstalled with Addon Tools)
</details>
<details>
<summary>Remove intermediates</summary>
```
[ 'OS=="linux"', { 'action' : [ [ 'OS=="linux"', { 'action' : [
'<(rm)', '<(rm)',
'<(module_root_dir)/build/Release/obj.target/addon/cpp/addon.o', '<(module_root_dir)/build/Release/obj.target/addon/cpp/addon.o',
@ -88,17 +119,22 @@ are accessible as shown below.
'<(module_root_dir)/build/Release/addon.*', '<(module_root_dir)/build/Release/addon.*',
'<(module_root_dir)/build/Release/obj/addon/*.*' '<(module_root_dir)/build/Release/obj/addon/*.*'
] } ], ] } ],
``` ```
Build-files can be removed in a separate build-step with `<(rm)`. Those are
usually PDB and OBJ files, which are rather big. However, in case of a hardcore
debug session you might want to comment this out.
</details> </details>
### Binary dependencies ### Binary dependency package
If you design a module with binary dependencies for several platforms, Addon Tools If you design a module with binary dependencies for several platforms, **Addon Tools**
would encourage you to abide by the following rules: would encourage you to abide by the following rules:
* Your binary directories are: * Your binary directories are:
* bin-win32 * bin-win32
* bin-win64 * bin-win64
* bin-linux32 * bin-linux32
@ -108,18 +144,18 @@ would encourage you to abide by the following rules:
* The following piece of code in your `index.js` without changes. Method `paths()` * The following piece of code in your `index.js` without changes. Method `paths()`
is described [here](#indexjs). is described [here](#indexjs).
``` ```
module.exports = require('addon-tools-raub').paths(__dirname); module.exports = require('addon-tools-raub').paths(__dirname);
``` ```
* Your whole `binding.gyp`: * Your whole **binding.gyp**:
<details> <details>
<summary>Show Snippet</summary> <summary>Show binding.gyp</summary>
``` ```
{ {
'variables': { 'variables': {
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")', 'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'rem' : '<!(node -e "require(\'.\').rem()")', 'rem' : '<!(node -e "require(\'.\').rem()")',
@ -139,63 +175,25 @@ module.exports = require('addon-tools-raub').paths(__dirname);
]}]], ]}]],
} }
] ]
} }
```
``` Notice the `XALL` variable here. If the package is installed with `npm i`, then
quite expectedly all but the required arch directories are removed. But with
`npm i --XALL` you can keep all the binaries. It might be useful when debugging
multiple archs and switching Node.js versions with
[NVM](https://github.com/creationix/nvm).
Notice the `XALL` variable here. If the package is installed with `npm i`, then </details>
quite expectedly all but the required arch directories are removed. But with
`npm i --XALL` you can keep all the binaries. It might be useful when debugging
multiple archs and switching Node.js versions with
[NVM](https://github.com/creationix/nvm).
</details>
### Compiled addon ### Compiled addon
If you always copy your compiled addon to the `binary` directory, it will be easy to It is easy to build a C++ addon with **Addon Tools**. To have a full picture, you
`require()` it without any hesitation. For copying, you can use the following snippet: can view the
[official example](https://github.com/node-3d/addon-tools-raub/tree/master/examples/addon).
<details> The main file for an addon is **binding.gyp**. Here's
<summary>Show Snippet</summary>
```
{
'target_name' : 'make_directory',
'type' : 'none',
'dependencies' : ['MY_ADDON'],
'actions' : [{
'action_name' : 'Directory created.',
'inputs' : [],
'outputs' : ['build'],
'action': ['<(mkdir)', '-p', 'binary']
}],
},
{
'target_name' : 'copy_binary',
'type' : 'none',
'dependencies' : ['make_directory'],
'actions' : [{
'action_name' : 'Module copied.',
'inputs' : [],
'outputs' : ['binary'],
'action' : ['<(cp)', 'build/Release/MY_ADDON.node', 'binary/MY_ADDON.node'],
}],
},
```
</details>
Here `MY_ADDON` should be replaced by any name you like. Then require like
this:
```
module.exports = require('./binary/MY_ADDON');
```
#### Generic addon snippet
<details> <details>
@ -211,6 +209,7 @@ module.exports = require('./binary/MY_ADDON');
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")', 'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")', 'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")',
'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")', 'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")',
'binary' : '<!(node -e "require(\'addon-tools-raub\').bin()")',
'EXT_LIB_include' : '<!(node -e "require(\'node-deps-EXT_LIB-raub\').include()")', 'EXT_LIB_include' : '<!(node -e "require(\'node-deps-EXT_LIB-raub\').include()")',
'EXT_LIB_bin' : '<!(node -e "require(\'node-deps-EXT_LIB-raub\').bin()")', 'EXT_LIB_bin' : '<!(node -e "require(\'node-deps-EXT_LIB-raub\').bin()")',
}, },
@ -257,7 +256,9 @@ module.exports = require('./binary/MY_ADDON');
'msvs_settings' : { 'msvs_settings' : {
'VCCLCompilerTool' : { 'VCCLCompilerTool' : {
'AdditionalOptions' : [ 'AdditionalOptions' : [
'/O2','/Oy','/GL','/GF','/Gm-','/EHsc', '/O2','/Oy', # Comment this for debugging
# '/Z7', # Unomment this for debugging
'/GL','/GF','/Gm-','/EHsc',
'/MT','/GS','/Gy','/GR-','/Gd', '/MT','/GS','/Gy','/GR-','/Gd',
] ]
}, },
@ -278,7 +279,7 @@ module.exports = require('./binary/MY_ADDON');
'action_name' : 'Directory created.', 'action_name' : 'Directory created.',
'inputs' : [], 'inputs' : [],
'outputs' : ['build'], 'outputs' : ['build'],
'action': ['<(mkdir)', '-p', 'binary'] 'action': ['<(mkdir)', '-p', '<(binary)']
}], }],
}, },
{ {
@ -289,7 +290,7 @@ module.exports = require('./binary/MY_ADDON');
'action_name' : 'Module copied.', 'action_name' : 'Module copied.',
'inputs' : [], 'inputs' : [],
'outputs' : ['binary'], 'outputs' : ['binary'],
'action' : ['<(cp)', 'build/Release/MY_ADDON.node', 'binary/MY_ADDON.node'], 'action' : ['<(cp)', 'build/Release/MY_ADDON.node', '<(binary)/MY_ADDON.node'],
}], }],
}, },
@ -326,6 +327,13 @@ module.exports = require('./binary/MY_ADDON');
} }
``` ```
Then require the built module like this:
```
const { binPath } = require('addon-tools-raub');
const core = require(`./${binPath}/MY_ADDON`);
```
</details> </details>
@ -337,17 +345,17 @@ There is a C++ header file, `addon-tools.hpp`, shipped with this package. It
introduces several useful macros and utilities. Also it includes Nan automatically, introduces several useful macros and utilities. Also it includes Nan automatically,
so that you can replace: so that you can replace:
``` ```
// #include <v8.h> // node.h includes it // #include <v8.h> // already in node.h
// #include <node.h> // nan.h includes it // #include <node.h> // already in nan.h
#include <nan.h> #include <nan.h>
``` ```
with with
``` ```
#include <addon-tools.hpp> // or event-emitter.hpp #include <addon-tools.hpp> // or event-emitter.hpp
``` ```
In gyp, the include directory should be set for your addon to know where to get it. In gyp, the include directory should be set for your addon to know where to get it.
As it was mentioned above, this can be done automatically. Also an actual path to the As it was mentioned above, this can be done automatically. Also an actual path to the
@ -495,7 +503,8 @@ NAN_METHOD(test) {
... ...
``` ```
NOTE: The conversion from `Nan::Utf8String` to `std::string` (via `char *`) is possible with unary `*` operator. NOTE: The conversion from `Nan::Utf8String` to `std::string` (via `char *`)
is possible with unary `*` operator.
</details> </details>
@ -576,10 +585,9 @@ the given JS value. Does not accept Array, checked with `IsArrayBufferView()`.
Returns `NULL` for empty JS values. For unacceptable values throws TypeError. Returns `NULL` for empty JS values. For unacceptable values throws TypeError.
* `void *getImageData(value)` - if value is a TypedArray, then the result of * `void *getData(value)` - if value is a TypedArray, then the result of
`getArrayData(value)` is returned. Otherwise if value has `'data'` property, it's `getArrayData(value)` is returned. Otherwise if value has `'data'` property, it's
content is then returned as `node::Buffer`. Returns `NULL` for empty JS values. content is then returned as `node::Buffer`. Returns `nullptr` in other cases.
For unacceptable values throws TypeError.
</details> </details>
@ -591,10 +599,10 @@ For unacceptable values throws TypeError.
Exports: Exports:
* `paths(dir)` - function. Returns a set of platform dependent paths depending on * `paths(dir)` - function. Returns a set of platform dependent paths depending on
input `dir`. input `dir`.
* `bin()` - prints platform binary path. * `bin()` - prints platform binary directory absolute path.
* `rem()` - prints a space-separated list of binary paths to be cleaned on this platform. * `rem()` - prints a space-separated list of binary paths to be cleaned on this platform.
* `include()` - prints include directory for this `dir`. * `include()` - prints include directory for this `dir`.
* `binPath` - platform binary path. * `binPath` - platform binary directory absolute path.
* `remPath` - a space-separated list of binary paths to be cleaned on this platform. * `remPath` - a space-separated list of binary paths to be cleaned on this platform.
* `includePath` - include directory for this `dir`. * `includePath` - include directory for this `dir`.
* `root()` - prints where `'addon-tools-raub'` module is situated. * `root()` - prints where `'addon-tools-raub'` module is situated.
@ -603,6 +611,8 @@ input `dir`.
* `rm()` - prints the location of `'_rm.bat'` file on Windows and plain `rm` on Unix. * `rm()` - prints the location of `'_rm.bat'` file on Windows and plain `rm` on Unix.
* `cp()` - prints the location of `'_cp.bat'` file on Windows and plain `cp` on Unix. * `cp()` - prints the location of `'_cp.bat'` file on Windows and plain `cp` on Unix.
* `mkdir()` - prints the location of `'_mkdir.bat'` file on Windows and plain `mkdir` on Unix. * `mkdir()` - prints the location of `'_mkdir.bat'` file on Windows and plain `mkdir` on Unix.
* `bin()` - prints platform binary directory name.
* `binPath` - platform binary directory name.
* `rootPath` - where `'addon-tools-raub'` module is situated. * `rootPath` - where `'addon-tools-raub'` module is situated.
* `includePath` - both `'addon-tools-raub'` and `'nan'` include paths. * `includePath` - both `'addon-tools-raub'` and `'nan'` include paths.
* `rmPath` - the location of `'_rm.bat'` file on Windows and plain `rm` on Unix. * `rmPath` - the location of `'_rm.bat'` file on Windows and plain `rm` on Unix.
@ -675,7 +685,7 @@ For Windows the `/y` flag was embedded.
A C++ implementation of [Events API](https://nodejs.org/api/events.html). A C++ implementation of [Events API](https://nodejs.org/api/events.html).
NOTE: This implementation has some minor deviations from the above standard. > Note: This implementation has some minor deviations from the above standard.
Specifically there is no static `EventEmitter.defaultMaxListeners` property. Specifically there is no static `EventEmitter.defaultMaxListeners` property.
However the dynamic one persists and is infinite (`0`) by default. However the dynamic one persists and is infinite (`0`) by default.
@ -721,7 +731,8 @@ class Example : public EventEmitter {
} }
``` ```
NOTE: Do not forget to call `EventEmitter::init()` once, in the module `init()`. > Note: Do not forget to call `EventEmitter::init()` once, in the module `init()`.
<details> <details>

2
package.json
View File

@ -1,7 +1,7 @@
{ {
"author": "Luis Blanco <luisblanco1337@gmail.com>", "author": "Luis Blanco <luisblanco1337@gmail.com>",
"name": "addon-tools-raub", "name": "addon-tools-raub",
"version": "1.0.0", "version": "2.0.0",
"description": "Helpers for Node.js addons and dependency packages", "description": "Helpers for Node.js addons and dependency packages",
"license": "MIT", "license": "MIT",
"main": "index.js", "main": "index.js",