{ "source": "addons.markdown", "modules": [ { "textRaw": "Addons插件", "name": "addons插件", "desc": "

Addons are dynamically linked shared objects. They can provide glue to C and\nC++ libraries. The API (at the moment) is rather complex, involving\nknowledge of several libraries:\n\n

\n

Addons插件就是动态连接库。它类似胶水，将c、c++和Node粘贴起来。它的API（目前来说）相当复杂，涉及到了几个类库的知识。\n\n

\n\n

Node statically compiles all its dependencies into the executable.\nWhen compiling your module, you don't need to worry about linking to\nany of these libraries.\n\n

\n

Node 静态编译了所有依赖到它的可执行文件中去了。当编译你的模块时，你不必担心无法连接上述那些类库。\n（译者：换而言之，你在编译自己的addons插件时，只管在头部 #include ，不必在binding.gyp中声明）\n\n

\n

All of the following examples are available for\ndownload and may be\nused as a starting-point for your own Addon.\n\n

\n

下面所有的例子都可以下载到：\n下载 \n这或许能成为你学习和创作自己addon插件的起点。\n\n

\n", "modules": [ { "textRaw": "Hello world（世界你好）", "name": "hello_world（世界你好）", "desc": "

To get started let's make a small Addon which is the C++ equivalent of\nthe following JavaScript code:\n\n

\n

作为开始，让我们用编写一个小的addon插件，这个addon插件的c++代码相当于下面的JavaScript代码。\n\n

\n
module.exports.hello = function() { return 'world'; };
\n

First we create a file hello.cc:\n\n

\n

首先我们创建一个 hello.cc文件:\n\n

\n
NODE_MODULE(hello, init)//译者：将addon插件名hello和上述init函数关联输出
\n

Note that all Node addons must export an initialization function:\n\n

\n

注意所有Node的addons插件都必须输出一个初始化函数：\n\n

\n
void Initialize (Handle<Object> exports);\nNODE_MODULE(module_name, Initialize)
\n

There is no semi-colon after NODE_MODULE as it's not a function (see\nnode.h).\n\n

\n

在NODE_MODULE之后没有分号，因为它不是一个函数（请参阅node.h）\n\n

\n

The module_name needs to match the filename of the final binary (minus the\n.node suffix).\n\n

\n

这个module_name（模块名）需要和最后编译生成的2进制文件名（减去.node后缀名）相同。\n\n

\n

The source code needs to be built into hello.node, the binary Addon. To\ndo this we create a file called binding.gyp which describes the configuration\nto build your module in a JSON-like format. This file gets compiled by\nnode-gyp.\n\n

\n

源代码需要生成在hello.node，这个2进制addon插件中。\n需要做到这些，我们要创建一个名为binding.gyp的文件，它描述了创建这个模块的配置，并且它的格式是类似JSON的。\n文件将被命令：node-gyp 编译。\n\n

\n
{\n  "targets": [\n    {\n      "target_name": "hello", //译者：addon插件名，注意这里的名字必需和上面NODE_MODULE中的一致\n      "sources": [ "hello.cc" ]  //译者：这是需要编译的源文件\n    }\n  ]\n}
\n

The next step is to generate the appropriate project build files for the\ncurrent platform. Use node-gyp configure for that.\n\n

\n

下一步是根据当前的操作系统平台，利用node-gyp configure命令，生成合适的项目文件。\n\n

\n

Now you will have either a Makefile (on Unix platforms) or a vcxproj file\n(on Windows) in the build/ directory. Next invoke the node-gyp build\ncommand.\n\n

\n

现在你会有一个Makefile (在Unix平台) 或者一个 vcxproj file\n(在Windows上)，它们都在build/ 文件夹中. \n然后执行命令 node-gyp build进行编译。\n（译者：当然你可以执行 node-gyp rebuild一步搞定）\n\n

\n

Now you have your compiled .node bindings file! The compiled bindings end up\nin build/Release/.\n\n

\n

现在你已经有了编译好的 .node 文件了，这个编译好的绑定文件会在目录 build/Release/下\n\n

\n

You can now use the binary addon in a Node project hello.js by pointing\nrequire to the recently built hello.node module:\n\n

\n

现在你可以使用这个2进制addon插件在Node项目hello.js 中了，通过指明require这个刚刚创建的hello.node模块使用它。\n\n

\n
console.log(addon.hello()); // 'world'
\n

Please see patterns below for further information or\n

\n

https://github.com/arturadib/node-qt for an example in production.\n\n

\n

请阅读下面的内容获得更多详情或者访问https://github.com/arturadib/node-qt获取一个生产环境的例子。\n\n

\n", "type": "module", "displayName": "Hello world（世界你好）" }, { "textRaw": "Addon patterns（插件方式）", "name": "addon_patterns（插件方式）", "desc": "

Below are some addon patterns to help you get started. Consult the online\nv8 reference for help with the various v8\ncalls, and v8's Embedder's Guide\nfor an explanation of several concepts used such as handles, scopes,\nfunction templates, etc.\n\n

\n

下面是一些帮助你开始编写addon插件的方式。参考这个在线的v8 手册用来帮助你调用各种v8接口， 然后是v8的 嵌入式开发向导 ，解释几个概念，如 handles, scopes,function templates等。\n\n\n

\n

In order to use these examples you need to compile them using node-gyp.\nCreate the following binding.gyp file:\n\n

\n

为了能跑起来这些例子，你必须用 node-gyp 来编译他们。\n创建一个binding.gyp 文件：\n\n

\n
{\n  "targets": [\n    {\n      "target_name": "addon",\n      "sources": [ "addon.cc" ]\n    }\n  ]\n}
\n

In cases where there is more than one .cc file, simply add the file name to\nthe sources array, e.g.:\n\n

\n

事实上可以有多个 .cc 文件, 就简单的在 sources 数组里加上即可，例子：\n\n

\n
"sources": ["addon.cc", "myexample.cc"]
\n

Now that you have your binding.gyp ready, you can configure and build the\naddon:\n\n

\n

现在你有了你的binding.gyp文件了，你可要开始执行configure 和 build 命令构建你的addon插件了\n\n

\n
$ node-gyp configure build
\n", "modules": [ { "textRaw": "Function arguments（函数参数）", "name": "function_arguments（函数参数）", "desc": "

The following pattern illustrates how to read arguments from JavaScript\nfunction calls and return a result. This is the main and only needed source\naddon.cc:\n\n

\n

下面的部分说明了如何从JavaScript的函数调用获得参数然后返回一个值。这是主要的内容并且仅需要源代码addon.cc。\n\n

\n
NODE_MODULE(addon, Init)
\n

You can test it with the following JavaScript snippet:\n\n

\n

你可以使用下面的JavaScript代码片段来测试它\n\n

\n
console.log( 'This should be eight:', addon.add(3,5) );
\n", "type": "module", "displayName": "Function arguments（函数参数）" }, { "textRaw": "Callbacks（回调）", "name": "callbacks（回调）", "desc": "

You can pass JavaScript functions to a C++ function and execute them from\nthere. Here's addon.cc:\n\n

\n

你可以传递JavaScript functions 到一个C++ function 并且执行他们，这里是 addon.cc文件:\n\n

\n
NODE_MODULE(addon, Init)
\n

Note that this example uses a two-argument form of Init() that receives\nthe full module object as the second argument. This allows the addon\nto completely overwrite exports with a single function instead of\nadding the function as a property of exports.\n\n

\n

注意这个例子对Init()使用了两个参数，将完整的 module 对象作为第二个参数传入。这允许addon插件完全的重写 exports，这样就可以用一个函数代替多个函数作为exports的属性了。\n\n

\n

To test it run the following JavaScript snippet:\n\n

\n

你可以使用下面的JavaScript代码片段来测试它\n\n

\n
addon(function(msg){\n  console.log(msg); // 'hello world'\n});
\n", "type": "module", "displayName": "Callbacks（回调）" }, { "textRaw": "Object factory（对象工厂）", "name": "object_factory（对象工厂）", "desc": "

You can create and return new objects from within a C++ function with this\naddon.cc pattern, which returns an object with property msg that echoes\nthe string passed to createObject():\n\n

\n

在这个addon.cc文件里用一个c++函数，你可以创建并且返回一个新的对象，这个新的对象拥有一个msg的属性，它的值是通过createObject()方法传入的\n\n

\n
NODE_MODULE(addon, Init)
\n

To test it in JavaScript:\n\n

\n

在js中测试如下:\n\n

\n
var obj1 = addon('hello');\nvar obj2 = addon('world');\nconsole.log(obj1.msg+' '+obj2.msg); // 'hello world'
\n", "type": "module", "displayName": "Object factory（对象工厂）" }, { "textRaw": "Function factory（函数工厂）", "name": "function_factory（函数工厂）", "desc": "

This pattern illustrates how to create and return a JavaScript function that\nwraps a C++ function:\n\n

\n

这次将展示如何创建并返回一个JavaScript function函数，这个函数其实是通过c++包装的。\n\n

\n
NODE_MODULE(addon, Init)
\n

To test:\n\n

\n

测试它:\n\n

\n
var fn = addon();\nconsole.log(fn()); // 'hello world'
\n", "type": "module", "displayName": "Function factory（函数工厂）" }, { "textRaw": "Wrapping C++ objects（包装c++对象）", "name": "wrapping_c++_objects（包装c++对象）", "desc": "

Here we will create a wrapper for a C++ object/class MyObject that can be\ninstantiated in JavaScript through the new operator. First prepare the main\nmodule addon.cc:\n\n

\n

这里将创建一个被c++包裹的对象或类MyObject，它是可以在JavaScript中通过new操作符实例化的。\n首先我们要准备主要的模块文件addon.cc:\n\n

\n
NODE_MODULE(addon, InitAll)
\n

Then in myobject.h make your wrapper inherit from node::ObjectWrap:\n\n

\n

然后在myobject.h文件中创建你的包装类，它继承自 node::ObjectWrap:\n\n

\n
#endif
\n

And in myobject.cc implement the various methods that you want to expose.\nHere we expose the method plusOne by adding it to the constructor's\nprototype:\n\n

\n

在文件 myobject.cc 可以实施各种你想要暴露给js的方法。 \n这里我们暴露方法名为 plusOne给就是，它表示将构造函数的属性加1.\n\n

\n
  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n

测试它:\n\n

\n
var obj = new addon.MyObject(10);\nconsole.log( obj.plusOne() ); // 11\nconsole.log( obj.plusOne() ); // 12\nconsole.log( obj.plusOne() ); // 13
\n", "type": "module", "displayName": "Wrapping C++ objects（包装c++对象）" }, { "textRaw": "Factory of wrapped objects（工厂包装对象）", "name": "factory_of_wrapped_objects（工厂包装对象）", "desc": "

This is useful when you want to be able to create native objects without\nexplicitly instantiating them with the new operator in JavaScript, e.g.\n\n

\n

这是非常有用的，当你想创建原生的JavaScript对象时，又不想明确的使用JavaScript的new操作符。\n\n

\n
var obj = addon.createObject();\n// 用上面的方式代替下面的:\n// var obj = new addon.Object();
\n

Let's register our createObject method in addon.cc:\n\n

\n

让我们注册在 addon.cc 文件中注册createObject方法:\n\n

\n
NODE_MODULE(addon, InitAll)
\n

In myobject.h we now introduce the static method NewInstance that takes\ncare of instantiating the object (i.e. it does the job of new in JavaScript):\n\n

\n

在myobject.h文件中，我们现在介绍静态方法NewInstance，它能够实例化对象（举个例子，它的工作就像是 在JavaScript中的new` 操作符。）\n\n

\n
#endif
\n

The implementation is similar to the above in myobject.cc:\n\n

\n

这里的处理方式和上面的 myobject.cc很像:\n\n

\n
  return scope.Close(Number::New(obj->counter_));\n}
\n

Test it with:\n\n

\n

测试它:\n\n

\n
var obj2 = createObject(20);\nconsole.log( obj2.plusOne() ); // 21\nconsole.log( obj2.plusOne() ); // 22\nconsole.log( obj2.plusOne() ); // 23
\n", "type": "module", "displayName": "Factory of wrapped objects（工厂包装对象）" }, { "textRaw": "Passing wrapped objects around（传递包装的对象）", "name": "passing_wrapped_objects_around（传递包装的对象）", "desc": "

In addition to wrapping and returning C++ objects, you can pass them around\nby unwrapping them with Node's node::ObjectWrap::Unwrap helper function.\nIn the following addon.cc we introduce a function add() that can take on two\nMyObject objects:\n\n

\n

除了包装和返回c++对象以外，你可以传递他们并且通过Node的node::ObjectWrap::Unwrap帮助函数解包装他们。\n在下面的addon.cc 文件中，我们介绍了一个函数add()，它能够获取2个MyObject对象。\n\n

\n
NODE_MODULE(addon, InitAll)
\n

To make things interesting we introduce a public method in myobject.h so we\ncan probe private values after unwrapping the object:\n\n

\n

为了使事情变得有趣，我们在 myobject.h 采用一个公共的方法，所以我们能够在unwrapping解包装对象之后使用私有成员的值。\n\n

\n
#endif
\n

The implementation of myobject.cc is similar as before:\n\n

\n

myobject.cc文件的处理方式和前面类似\n\n

\n
  return scope.Close(instance);\n}
\n

Test it with:\n\n

\n

测试它:\n\n

\n
var obj1 = addon.createObject(10);\nvar obj2 = addon.createObject(20);\nvar result = addon.add(obj1, obj2);\n\nconsole.log(result); // 30\n\n\nconsole.log(result); // 30
\n", "type": "module", "displayName": "Passing wrapped objects around（传递包装的对象）" } ], "type": "module", "displayName": "Addon patterns（插件方式）" } ], "type": "module", "displayName": "Addons插件" } ] }