From 4b642f6a2d903505eccc8d15c70803c0a6344fd9 Mon Sep 17 00:00:00 2001 From: raub Date: Mon, 14 May 2018 11:11:11 +0300 Subject: [PATCH] :memo: Update docs and version for v2.0.0 release --- README.md | 313 ++++++++++++++++++++++++++------------------------- package.json | 2 +- 2 files changed, 163 insertions(+), 152 deletions(-) diff --git a/README.md b/README.md index b66cc18..a810a70 100644 --- a/README.md +++ b/README.md @@ -47,155 +47,153 @@ Useful links: [V8 Ref](https://v8docs.nodesource.com/node-0.8/d2/dc3/namespacev8 ### binding.gyp -* Crossplatform commands can be put into the variables for later use. - -``` -'variables': { - 'rm' : ' -Show Snippet - -``` - [ 'OS=="linux"', { 'action' : [ - '<(rm)', - '<(module_root_dir)/build/Release/obj.target/addon/cpp/addon.o', - '<(module_root_dir)/build/Release/addon.node' - ] } ], - [ 'OS=="mac"', { 'action' : [ - '<(rm)', - '<(module_root_dir)/build/Release/obj.target/addon/cpp/addon.o', - '<(module_root_dir)/build/Release/addon.node' - ] } ], - [ 'OS=="win"', { 'action' : [ - '<(rm)', - '<(module_root_dir)/build/Release/addon.*', - '<(module_root_dir)/build/Release/obj/addon/*.*' - ] } ], -``` - +Crossplatform commands + + ``` + 'variables': { + 'rm' : ' -### Binary dependencies +
-If you design a module with binary dependencies for several platforms, Addon Tools +Addon binary directory + + ``` + 'variables': { + 'binary' : ' + + +
+ +Include directories + + ``` + 'include_dirs': [ + ' + + +
+ +Remove intermediates + + ``` + [ 'OS=="linux"', { 'action' : [ + '<(rm)', + '<(module_root_dir)/build/Release/obj.target/addon/cpp/addon.o', + '<(module_root_dir)/build/Release/addon.node' + ] } ], + [ 'OS=="mac"', { 'action' : [ + '<(rm)', + '<(module_root_dir)/build/Release/obj.target/addon/cpp/addon.o', + '<(module_root_dir)/build/Release/addon.node' + ] } ], + [ 'OS=="win"', { 'action' : [ + '<(rm)', + '<(module_root_dir)/build/Release/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. + +
+ + +### Binary dependency package + +If you design a module with binary dependencies for several platforms, **Addon Tools** would encourage you to abide by the following rules: * Your binary directories are: + * bin-win32 * bin-win64 * bin-linux32 * bin-linux64 * bin-mac64 - + * The following piece of code in your `index.js` without changes. Method `paths()` is described [here](#indexjs). - -``` -module.exports = require('addon-tools-raub').paths(__dirname); -``` - -* Your whole `binding.gyp`: - -
- -Show Snippet - -``` -{ - 'variables': { - 'rm' : ' + + ``` + module.exports = require('addon-tools-raub').paths(__dirname); + ``` + +* Your whole **binding.gyp**: + +
+ + Show binding.gyp + + ``` + { + 'variables': { + 'rm' : ' ### Compiled addon -If you always copy your compiled addon to the `binary` directory, it will be easy to -`require()` it without any hesitation. For copying, you can use the following snippet: +It is easy to build a C++ addon with **Addon Tools**. To have a full picture, you +can view the +[official example](https://github.com/node-3d/addon-tools-raub/tree/master/examples/addon). -
- -Show Snippet - -``` -{ - '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'], - }], -}, -``` - -
- -Here `MY_ADDON` should be replaced by any name you like. Then require like -this: - -``` -module.exports = require('./binary/MY_ADDON'); -``` - -#### Generic addon snippet +The main file for an addon is **binding.gyp**. Here's
@@ -211,6 +209,7 @@ module.exports = require('./binary/MY_ADDON'); 'rm' : ' @@ -336,18 +344,18 @@ module.exports = require('./binary/MY_ADDON'); 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, so that you can replace: - -``` -// #include // node.h includes it -// #include // nan.h includes it -#include -``` - -with - -``` -#include // or event-emitter.hpp -``` + + ``` + // #include // already in node.h + // #include // already in nan.h + #include + ``` + + with + + ``` + #include // or event-emitter.hpp + ``` 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 @@ -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.
@@ -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. -* `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 -content is then returned as `node::Buffer`. Returns `NULL` for empty JS values. -For unacceptable values throws TypeError. +content is then returned as `node::Buffer`. Returns `nullptr` in other cases.
@@ -591,10 +599,10 @@ For unacceptable values throws TypeError. Exports: * `paths(dir)` - function. Returns a set of platform dependent paths depending on 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. * `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. * `includePath` - include directory for this `dir`. * `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. * `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. +* `bin()` - prints platform binary directory name. +* `binPath` - platform binary directory name. * `rootPath` - where `'addon-tools-raub'` module is situated. * `includePath` - both `'addon-tools-raub'` and `'nan'` include paths. * `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). -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. 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()`. +
diff --git a/package.json b/package.json index e50de92..cb3d007 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "author": "Luis Blanco ", "name": "addon-tools-raub", - "version": "1.0.0", + "version": "2.0.0", "description": "Helpers for Node.js addons and dependency packages", "license": "MIT", "main": "index.js",