Cocos 中的自动绑定
发表于2016-02-02
一、语言绑定技术
绑定技术是指在目标语言中创造一套简单的 API 接口并将它指向另一种语言中的实际实现。往往其功能的实现非常庞大复杂，可能是目标语言所无法承载的，但是通过这种方式可以使目标语言具备使用这些功能的能力。
二、Cocos中的脚本绑定
早在2012年，时任 Zygna 工程师的 Rolando Abarca 主导开发了一套基于 Cocos2d-x 和 SpiderMonkey 的 JavaScript 自动绑定技术。这套绑定技术将 Cocos2d-x 的 C++ API 暴露到了JavaScript 语言中，使得开发者可以使用 JavaScript 来编写游戏代码，并享受 C++ 底层引擎框架高性能。后来 Cocos2d-x 团队的成员用同样的框架导出了 Lua API，完成了 C++ 到 Lua 的绑定。
这也是目前 Cocos 中脚本绑定技术的根基，由 Cocos 团队一直维护至今。目前 Cocos 的三种语言支持 C++/Lua/JS，其中的 Lua 和 JS 就是脚本绑定技术的成果。
三、绑定基本框架
让我们来先看一下 Cocos 引擎脚本绑定技术的框架图：
可以看到 JS 绑定和 Lua 绑定技术的结构是一致的，让我们自底向上一层一层解析：
1、首先在最底层的是 Cocos2d-x 的 C++ 实现，绑定技术归根结底只是将其实现的功能暴露到对应的语言层。
2、往上一层是 JavaScript 和 Lua 的脚本引擎，其中 JS 绑定使用的是 SpiderMonkey 作为JavaScript引擎。SpiderMonkey 是由 Mozilla 维护的世界上第一个 JavaScript 引擎，也是目前 JavaScript 执行性能最优秀的引擎之一。
3、脚本引擎这一层提供了两个重要的能力：首先当然是执行脚本的能力，但是最重要的是它还提供了对脚本层进行访问的 C API。第二个能力成为了 C++ 引擎到脚本层的桥梁，让 C++ 可以截获脚本层的 API 调用，访问脚本环境中的变量，构造新的对象，主动调用脚本层的函数等。
4、在脚本引擎提供的 C API 基础之上，Cocos 引擎中通过两种方式将 C++ API 暴露到脚本层：自动绑定和手动绑定。同时，使用纯脚本实现来改造一些 API 让其更适合脚本程序员的习惯，并且提供一些不需要绑定的 API。这三者共同构成了脚本层 API。
5、有了脚本层的 API，开发者们自然就顺理成章得可以使用脚本来开发 Cocos 游戏了。
四、关于自动绑定
自动绑定技术是 Cocos 引擎最引以为傲的利器之一，为什么说它是 Cocos 脚本绑定技术的根基呢？绑定本身并不困难，有了脚本引擎和它的 API 就可以完成，真正困难在于以下几点：
1、如何将 Cocos 中如此巨量的 C++ API 全部绑定出来？
2、 因为 Cocos 的版本迭代所带来的变化势必会影响到其绑定代码，那么如何保证绑定代码的可维护性？
3、如何让一个不懂得绑定技术的人也可以为他所做的功能提供脚本绑定？
正因为这些困难，自动化的绑定技术才真正让 Cocos 的脚本绑定成为现实。目前 Cocos 内部主要的绑定代码都是由自动绑定工具生成的，并且版本迭代当中，都会根据代码修改自动更新自动绑定代码。除此之外，用户也可以自由使用自动绑定工具绑定自己编写的 C++ 类。
Cocos 中的自动绑定技术基于 Bindings Generator 工具，配合上 C++ 类配置信息，通过扫描 C++ 类的头文件，Bindings Generator 就可以生成所有公有 API 的脚本绑定代码。
五、关于手动绑定
虽然 Bindings Generator 已经非常强大，但是它依然有其局限性。目前的 Bindings Generator 的局限性主要是以下的几点：
1、只能够针对类生成绑定，不可以绑定结构体，独立函数等
2、不能够生成 Delegate 类型的 API，因为脚本中的对象是无法继承 C++ 中的 Delegate 类并重写其中的 Delegate 函数的。
3、子类中重写了父类的 API 的同时，又重载了这个 API。
4、部分 API 实现内容并没有完全体现在其 API 定义中。
5、在运行时由 C++ 主动调用的 API。
对于这些类型的 API，我们就需要通过手动编写绑定代码来将这些 API 绑定到脚本层。手动绑定出来的绑定代码的基本原理和自动绑定一致，只是自动绑定因其局限性绑定出来的内容可能会导致编译失败或者行为错误。
前三种类型的 API 通过自动绑定都可以解决，但是第四种类型，无法简单通过绑定来实现。因为绑定技术实现的是将 C++ 暴露到脚本层，使得脚本层可以调用 C++ 层实现的 API。而从 C++ 调用的 API，并不能主动得调用到脚本层，这是相反的过程。所以就需要在 C++ 源码中做一些特殊的处理，比如 Cocos 中 Node 类的 onEnter，update 函数，都有做类似的处理。同时，Cocos 中的 Action 类，都无法在脚本层被继承，根本原因也在于此，脚本层重写的 update 函数无法被 C++ 的 ActionManager调用到。
Cocos 中的自动绑定依赖于 Bindings Generator 工具，这个 python 工具通过配置文件来解析需要绑定的类的头文件，并且按照一定规则生成类的 API 的绑定代码。
六、Bindings Generator
Bindings Generator 工具是自动绑定的核心工具，它可以将 C++ 类的公共方法和公共属性绑定到脚本层。自动绑定工具非常强大，不过它还是有以下几个限制：
1、只能够针对类生成绑定，不可以绑定结构体，独立函数等。
2、不能够生成 Delegate 类型的 API，因为脚本中的对象是无法继承 C++ 中的 Delegate 类并重写其中的 Delegate 函数的。
3、子类中重写了父类的 API 的同时，又重载了这个 API。
4、部分 API 实现内容并没有完全体现在其 API 定义中。
5、在运行时由 C++ 主动调用的 API。
也就是说，除了这几种情况以外，都可以通过自动绑定工具将 C++ 类绑定到脚本层。
七、配置环境
# Mac OS X 环境配置
· Mac OS X 中默认包含 Python 2.7，如果你的机器上不包含 Python，可以通过其他方式:
· 安装 HomeBrew 并执行`brew install python`
· 通过 pip 安装其他 Python 依赖库
sudo easy_install pip
sudo pip install PyYAML
sudo pip install Cheetah
· 从 Google 下载 NDK r9d+
· 在 `~/.bash_profile` 中设置 `PYTHON_ROOT` 和 `NDK_ROOT` 环境变量
# Windows环境配置
· 下载并安装 Python 2.7
· 添加 Python 的安装路径（e.g. C:Python27）到 windows 的 `PATH` 环境变量中
· 下载并安装 pyyaml
· 下载 pyCheetah 并解压到 Python 路径下的 `Libsite-packages`
· 从 Google 下载 64bit NDK r9d+
· 设置 `PYTHON_ROOT` 和 `NDK_ROOT` 环境变量
至此绑定工具的基本环境已经配置成功。
八、基本原理
自动绑定工具最核心的工作原理是通过 libclang 分析 C++ 头文件，以一定的绑定规则和绑定代码模版，针对 C++ 类的公共方法和属性一一对应生成每个方法的绑定代码和每个属性的 Getter/Setter 方法。下面让我们用倒推法来分析这个过程：
# 绑定结果
最终，自动绑定的结果是一个 C++ 文件和一个头文件，其中包含：
1、所有 API 的绑定函数，用于桥接脚本环境中的 API 和 C++ API，在脚本层调用相应 API 的时候，实际调用的是绑定函数，并由绑定函数转发调用 C++ API。
2、C++ 类的绑定函数，用于在脚本环境中创建对应的类，它会将所有 API 的绑定函数注册到脚本类中，这样脚本中调用这些 API 就会调用到绑定函数。
3、用来注册所有绑定的函数，这个函数中会调用 C++ 类的绑定函数，调用这个注册函数会让这些 C++ 类被实际注册到脚本环境中。
# 注册和调用过程
以 `Node::setOpacity` 为例，可以在 `cocos2d-x/cocos/scripting/js-bindings/auto/jsb_cocos2dx_auto.cpp` 中找到它的 JavaScript 绑定代码。
上面所描述的注册过程如下：
再来看 `js_cocos2dx_Node_setOpacity` 的实现：
bool js_cocos2dx_Node_setOpacity(JSContext *cx, uint32_t argc, jsval *vp)
{
// 1. 通过SpiderMonkey API获取脚本层传入的所有参数
JS::CallArgs args = JS::CallArgsFromVp(argc, vp);
bool ok = true;
// 2. 通过SpiderMonkey API获取本次调用的脚本层调用者对象
JS::RootedObject obj(cx, args.thisv().toObjectOrNull());
js_proxy_t *proxy = jsb_get_js_proxy(obj);
// 3. 转换脚本层调用对象为其对应的C++对象
cocos2d::Node* cobj = (cocos2d::Node *)(proxy ? proxy->ptr : NULL);
JSB_PRECONDITION2( cobj, cx, false, "js_cocos2dx_Node_setOpacity : Invalid Native Object");
if (argc == 1) {
uint16_t arg0;
// 4. 转换脚本层传入的参数对象为C++值或对象
ok &= jsval_to_uint16(cx, args.get(0), &arg0);
JSB_PRECONDITION2(ok, cx, false, "js_cocos2dx_Node_setOpacity : Error processing arguments");
// 5. 最终使用转换过的参数调用实际的C++ API
cobj->setOpacity(arg0);
// 6. 设置脚本层函数调用的返回值
args.rval().setUndefined();
return true;
}
JS_ReportError(cx, "js_cocos2dx_Node_setOpacity : wrong number of arguments: %d, was expecting %d", argc, 1);
return false;
}
代码中通过注释标注了一个绑定函数调用时的完整步骤：
可以看出，整个过程实际上就是在 C++ 和脚本层之间进行对象的转换，并转发脚本层函数调用到 C++ 层的过程。所有 API 的绑定，不论其实现多复杂，都是这样的一个过程。
# 分析 C++ 头文件
为了绑定出这样的结果，必须要对 C++ 头文件进行分析，然后对 C++ 类的 API 一一生成绑定代码。自动绑定工具使用 libclang 的 python API 对 C++ 头文件进行语法分析。绑定的过程大致如下：
1、创建绑定代码输出文件。
2、递归扫描需要绑定的头文件。
3、通过 libclang 的 clang.cindex python 模块找到所有需要绑定的类，公共 API 等。
4、按照模版生成类绑定函数，API 绑定函数，绑定注册函数并输出到文件中。
# 绑定规则和绑定模版
当然，绑定过程并不是不可控的，其实有很多可定制的规则是通过自动绑定的配置文件来配置的。有了这些配置，开发者就可以选择绑定的具体内容和方式。其中可定制的重要属性如下：
1、target_namespace：脚本中的目标命名空间，比如 cc, spine 等。
2、clang_flags：clang 标签，其中可以添加预编译宏。
3、macro_judgement：将绑定出的绑定代码包裹在一个条件编译块中，避免由预编译宏控制的 API 被绑定导致的编译问题。
4、 headers：需要被绑定的头文件列表，以空格分隔，头文件将被递归扫描。
5、cpp_headers：绑定代码需要包含但是不需要被绑定工具扫描的头文件列表。
6、classes：需要被绑定的类名列表，以空格分隔。
7、classes_need_extend：需要在脚本层被继承的类列表，以空格分隔。
8、skip：需要忽略的 API 列表，格式为 `ClassName::[api1 api2]`，不同的类以逗号分隔。
9、rename_functions：需要被重命名的函数，会将 C++ 中的函数绑定为指定名字的脚本函数，格式为 `ClassName::[cppFunctionName=scriptFunctionName ...]`，不同的类以逗号分隔。
10、rename_classes：需要被重命名的类，会将 C++ 中的类名绑定为指定的脚本类名，格式为 `CppClassName::ScriptClassName`，以逗号分割。
11、classes_have_no_parents：没有父类的类列表，以空格分隔。
12、abstract_classes：没有构造函数的类列表，以空格分隔。
有了这些配置之后，自动绑定工具就知道哪些 API 要被绑定和以什么样的方式绑定。不过，还需要配合各种 API 的绑定代码模版才可以真正生成各种 API 的绑定函数。对于每一个特定的模版，它会读取 clang.cindex 解析出的类或 API 定义信息以及绑定配置信息，生成特定 API 的绑定代码。下面是目前自动绑定工具中的模版：
1、头文件和 cpp 文件的头部代码模版
2、 头文件和 cpp 文件的尾部代码模版
3、 头文件内容模版，包含脚本层类对象声明，原型对象声明和 API 绑定函数声明
4、类绑定函数模版
5、构造函数的绑定函数模版
6、静态函数的绑定函数模版
7、重载的静态函数的绑定函数模版
8、公共属性的绑定函数模版
9、公共方法的绑定函数模版
10、重载的公共方法的绑定函数模版
11、lambda 函数的绑定函数模版
# 转换函数
从上文的调用过程中可以看出，脚本层和 C++ 层的对象转换非常重要，而这个转换并不是自动的，自动绑定工具无法知道如何在各种 C++ 类型和脚本类型之间进行转换。这里没有任何捷径和魔法，所有类型的转换都必须使用脚本引擎的 C++ API 来完成转换。
这里就要提到转换函数了，对于核心引擎模块中的类型，C++ 和 JS 对象的互相转换函数在引擎目录下 `cocos/scripting/js-bindings/manual/js_manual_conversions.h` 中可以找到，C++ 和 Lua 对象的互相转换函数在引擎目录下 `cocos/scripting/lua-bindings/manual/LuaBasicConversions.h` 中。
以 JS 为例，转换函数中包含
1、 基础数据类型，如 int，long，boolean，char 等。
2、结构体，如 Color4B，Vec2，BlendFunc 等。
3、容器类型，如 Dictionary，ValueVector，ValueMap 等。
这里没有提到类实例对象的转换，是因为类对象的转换是自动完成的。所以，当开发者自己的 API 中包含自己定义的结构体或者特殊容器类型作为参数或返回值的时候，就需要编写自己的转换函数，转换函数的编写方法可以参考引擎内部的这些范例。
仅仅有转换函数还不够，还需要告诉自动绑定工具该对何种类型具体使用哪个转换函数，这就是 yaml 转换模版的工作了，JS 的转换模版可以在 `tools/bindings-generator/targets/spidermonkey/conversions.yaml` 中找到，Lua 的转换模版则位于 `tools/bindings-generator/targets/lua/conversions.yaml`。在转换模版中，`to_native` 定义了从脚本对象转换为 C++ 对象的模版，`from_native` 定义了从 C++ 对象到脚本对象的转换模版。
九、编写绑定脚本和配置文件
# 编写绑定配置文件
编写绑定配置文件并不是非常简单直观的事情，不过由于引擎中有大量的绑定范例，开发者完全可以以此为模版进行修改。请参考引擎目录中 `tools/tojs` 和 `tools/tolua` 下的 `.ini` 文件，并结合前面一个章节中解释的定制属性来编写自己需要的绑定配置文件。
# 使用绑定生成脚本
自动绑定工具的主体是 `tools/bindings-generator/generator.py` 这个 python 脚本。当生成自动绑定的时候，针对每一个 `ini` 配置文件调用的 python 命令如下：
python generator.py config_file.ini -s module_name -t spidermonkey|lua -o output_dir -n output_file_name
当然，单独对每一个 `ini` 文件生成绑定是可以的。不过也可以通过编写自动生成脚本的方式来自动处理。
具体可以参考引擎的自动绑定生成脚本，`tools/tojs/genbindings.py` 和 `tools/tolua/genbindings.py`
在引擎的自动绑定生成脚本中，配置了下面的一些参数：
1、NDK_ROOT 环境变量：指示 NDK 的根目录
2、PYTHON_BIN 环境变量：指示 Python 命令的路径
3、cocosdir：Cocos 引擎根目录，在用户工程下一般是 `frameworks/cocos2d-x/`
4、jsbdir：JSB 目录，在用户工程下一般是 `frameworks/cocos2d-x/cocos/scripting/js-bindings`
5、 cxx_generator_root：自动绑定工具路径，在用户工程下一般是 `tools/bindings-generator`
6、output_dir：生成的绑定文件存储路径
7、cmd_args：所有配置文件，及其对应的模块名称和输出文件名称
最终支持批量自动化生成引擎的自动绑定代码。
十、绑定自己的 C++ 类
对于用户自己扩展的 C++ 类，通过上面的自动绑定原理解读，其实已经可以尝试自己编写绑定生成脚本生成扩展类的绑定了。不过引擎中的绑定生成脚本已经考虑到这种需求，提供了扩展的方法，开发者需要的就是遵循下面的步骤：
1、编写自定义 C++ 类的绑定配置文件并保存到 `tools/tojs` 或者 `tools/tolua` 文件夹中。
2、 在 `tools/tojs/genbindings.py` 或 `tools/tolua/genbindings.py` 中找到 `custom_cmd_args`，在其中填写绑定模块。
3、运行 `genbindings.py` 即可生成自动绑定代码到 `frameworks/custom/auto` 文件夹中。
`custom_cmd_args` 的格式如下：
custom_cmd_args = {
'custom_module1.ini' : ('custom_module1', 'jsb_custom_module1_auto'),
'custom_module2.ini' : ('custom_module2', 'jsb_custom_module2_auto'),
}
其中键对应的是绑定配置文件文件名，括号中的第一个参数对应模块名，第二个参数对应输出文件的文件名。
十一、结语
以上就是 Bindings Generator 自动绑定工具的原理介绍和使用方法，希望这篇文章对于理解 Cocos2d-x 的自动绑定原理有所帮助。