addon-tools-raub
Advanced tools
This is a set of helpers for simplification and standardization of addons and dependency packages.
npm i -s addon-tools-raub
'variables': {
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")',
'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")',
},
'include_dirs': [
'<!@(node -e "require(\'addon-tools-raub\').include()")',
],
<(rm). [ '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/*.*'
] } ],
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:
The following piece of code in your index.js without changes. Method paths()
is described here.
module.exports = require('addon-tools-raub').paths(__dirname);
binding.gyp:{
'variables': {
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'rem' : '<!(node -e "require(\'.\').rem()")',
},
'targets': [
{
'target_name' : 'remove_extras',
'type' : 'none',
'actions' : [
{
'action_name' : 'Unnecessary binaries removed.',
'inputs' : [],
'outputs' : ['build'],
'action' : ['<(rm)', '-rf', '<@(rem)'],
}
],
}
]
}
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:
{
'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/addon');
EXT_LIB is the name of an Addon Tools compliant binary dependency module.MY_ADDON is the name of this addon.cpp directory.{
'variables': {
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")',
'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")',
'EXT_LIB_include' : '<!(node -e "require(\'node-deps-EXT_LIB-raub\').include()")',
'EXT_LIB_bin' : '<!(node -e "require(\'node-deps-EXT_LIB-raub\').bin()")',
},
'targets': [
{
'target_name': 'MY_ADDON',
'sources': [
'cpp/MY_ADDON.cpp',
],
'include_dirs': [
'<!(node -e "require(\'addon-tools-raub\').include()")',
'<(EXT_LIB_include)',
'<(module_root_dir)/include',
],
'library_dirs': [ '<(EXT_LIB_bin)' ],
'conditions': [
[
'OS=="linux"',
{
'libraries': [
'-Wl,-rpath,<(EXT_LIB_bin)',
'<(EXT_LIB_bin)/libEXT_LIB.so',
],
}
],
[
'OS=="mac"',
{
'libraries': [
'-Wl,-rpath,<(EXT_LIB_bin)',
'<(EXT_LIB_bin)/EXT_LIB.dylib',
],
}
],
[
'OS=="win"',
{
'libraries': [ 'EXT_LIB.lib' ],
'defines' : [
'WIN32_LEAN_AND_MEAN',
'VC_EXTRALEAN'
],
'msvs_version' : '2013',
'msvs_settings' : {
'VCCLCompilerTool' : {
'AdditionalOptions' : [
'/O2','/Oy','/GL','/GF','/Gm-','/EHsc',
'/MT','/GS','/Gy','/GR-','/Gd',
]
},
'VCLinkerTool' : {
'AdditionalOptions' : ['/OPT:REF','/OPT:ICF','/LTCG']
},
},
}
],
],
},
{
'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'],
}],
},
{
'target_name' : 'remove_extras',
'type' : 'none',
'dependencies' : ['copy_binary'],
'actions' : [{
'action_name' : 'Build intermediates removed.',
'inputs' : [],
'outputs' : ['cpp'],
'conditions' : [
[ 'OS=="linux"', { 'action' : [
'rm',
'<(module_root_dir)/build/Release/obj.target/MY_ADDON/cpp/MY_ADDON.o',
'<(module_root_dir)/build/Release/obj.target/MY_ADDON.node',
'<(module_root_dir)/build/Release/MY_ADDON.node'
] } ],
[ 'OS=="mac"', { 'action' : [
'rm',
'<(module_root_dir)/build/Release/obj.target/MY_ADDON/cpp/MY_ADDON.o',
'<(module_root_dir)/build/Release/MY_ADDON.node'
] } ],
[ 'OS=="win"', { 'action' : [
'<(_del)',
'<(module_root_dir)/build/Release/MY_ADDON.*',
'<(module_root_dir)/build/Release/obj/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 <v8.h> // node.h includes it
// #include <node.h> // nan.h includes it
#include <nan.h>
with
#include <addon-tools.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 directory is exported from the module and is accessible like this:
require('addon-tools-raub').include
In the file, currently there are following helpers:
NAN_HS - creates a HandleScope. Also, you do not need them within NAN_METHOD,
NAN_SETTER, and NAN_GETTER, as it is stated in
Nan doc.
So it is most likely to be used in native callbacks.void windowFocusCB(GLFWwindow *window, int focused) { NAN_HS;
...
}
...
glfwSetWindowFocusCallback(window, windowFocusCB);
These checks throw JS TypeError if not passed. Here T is always used as a typename
in error messages. C is
v8::Value
check method, like IsObject(). I is the index of argument as in info[I],
starting from 0.
N arguments passedI is undefined or nullI is approved by C check.I is approved by C check or empty.value is approved by C check.Two types of argument retrieval are supported: REQ_ and LET_. The difference
is that LET_ allows the argument to be empty, using some zero-default in this case.
I is the index of argument as in info[I],
starting from 0. VAR is the name of the Local<Value> variable to be created.
NAN_METHOD(testScene) {
REQ_UINT32_ARG(0, width);
REQ_UINT32_ARG(1, height);
LET_FLOAT_ARG(2, z);
// Variables created: unsigned int width, height; float z;
...
Set-helpers for string and numeric keys. String keys are converted to JS strings automatically.
Simplified accessor assignment, adds accessors of NAME for OBJ. Read accessor is
assumed to have the name NAME+'Getter' and write accessor is NAME+'Setter'.
void MyClass::init(Handle<Object> target) {
...
Local<ObjectTemplate> proto = ctor->PrototypeTemplate();
ACCESSOR_RW(proto, message);
...
}
NAN_GETTER(MyClass::messageGetter) { ...
NAN_SETTER(MyClass::messageSetter) { ...
Useful addition to NAN_SETTER macro.
NAN_SETTER(MyClass::messageSetter) { SETTER_UTF8_ARG;
// Variable created: Nan::Utf8String v;
...
T *getArrayData(value, num = NULL) - extracts TypedArray data of any type from
the given JS value. Does not accept Array, checked with IsArrayBufferView().
Returns NULL for empty JS values. For unacceptable values throws TypeError.
BYTE *getImageData(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.
Exports:
paths(dir) - function. Returns a set of platform dependent paths depending on
input dir.
bin() - prints platform binary 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.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.include() - prints both 'addon-tools-raub' and 'nan' include paths. Use with
node -e through list context command expansion <!@(...)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.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.cpPath - the location of '_cp.bat' file on Windows and plain cp on Unix.mkdirPath - the location of '_mkdir.bat' file on Windows and plain mkdir on Unix.Because of the differences between Windows and Unix command shells, often a whole lot of conditions have to be introduced in binding.gyp file. Now some of them can be easily omitted with the new crossplatform commands, supplied by this package.
This comes especially handy together with GYP's executable list expansion. For example a list of files to be removed for cleaning. Or a list of unnecessary binaries to be removed upon installation of a binary-dependency package.
On Unix, it will be an actual system mkdir, whereas on Windows it will use the
mkdir.bat file, located at the root of this package. This BAT file behaves
as if it was a mkdir -p ... call. You can still pass -p switch, which is
ignored. And the limitation is that you can not create a relative-path -p
folder. This can possibly be bypassed by supplying ./-p or something like this.
'variables': {
'mkdir' : '<!(node -e "require(\'addon-tools-raub\').mkdir()")',
},
...
'action' : ['<(mkdir)', '-p', 'binary'],
Disregard del vs rd aspect of Windows command line. Now the same command can
be used on all platforms to remove single and multiple files and directories.
'variables': {
'rm' : '<!(node -e "require(\'addon-tools-raub\').rm()")',
'rem' : '<!(node -e "require(\'.\').rem()")',
},
...
'action' : ['<(rm)', '-rf', '<@(rem)'],
For Windows the /y flag was embedded.
'variables': {
'cp' : '<!(node -e "require(\'addon-tools-raub\').cp()")',
},
...
'action' : ['<(cp)', 'a', 'b'],
A C++ implementation of Events API.
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.
An example can be found in examples/node-addon directory.
There is Example class, implemented in cpp/example.cpp, that inherits
EventEmitter behavior and is exported to JS.
For the C++ side EventEmitter has following public methods:
void emit(const std::string &name, int argc = 0, v8::Local<v8::Value> *argv = NULL)
emits an event with the given name and, optionally, some additional arguments where
argc is the number of arguments and argv is a pointer to the arguments array.
void on(const std::string &name, v8::Local<v8::Value> that, const std::string &method)
subscribes that[method] to receive name events from this emitter, basically
emitter.on(name, that[method]).
Be sure to add the include directory in binding.gyp:
'include_dirs': [
'<!@(node -e "require(\'addon-tools-raub\').include()")',
],
Include the event-emitter.hpp, it also includes addon-tools.hpp.
Inherit from EventEmitter, it already inherits from Nan::ObjectWrap:
#include <event-emitter.hpp>
class Example : public EventEmitter {
...
}
First add EventEmitter dynamic methods to the prototype via
static void extendPrototype(v8::Local<v8::FunctionTemplate> &proto) and then,
after constructor function instance is created,
static void extendConstructor(v8::Local<v8::Function> &ctorFn):
void Example::init(Handle<Object> target) {
Local<FunctionTemplate> proto = Nan::New<FunctionTemplate>(newCtor);
proto->InstanceTemplate()->SetInternalFieldCount(1);
proto->SetClassName(JS_STR("Example"));
// -------- dynamic
// Add EventEmitter methods
extendPrototype(proto);
Nan::SetPrototypeMethod(proto, "destroy", destroy);
// -------- static
Local<Function> ctor = Nan::GetFunction(proto).ToLocalChecked();
extendConstructor(ctor);
_constructor.Reset(ctor);
Nan::Set(target, JS_STR("Example"), ctor);
}
NOTE: after a v8::Function is created from the v8::FunctionTemplate, no
additional methods can be added to the prototype. Also static members can only
be added to the created v8::Function representing the constructor. This is why
there are 2 extend methods: extendPrototype and extendConstructor.
FAQs
Helpers for Node.js addons and dependency packages
The npm package addon-tools-raub receives a total of 308 weekly downloads. As such, addon-tools-raub popularity was classified as not popular.
We found that addon-tools-raub demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.