Cocos 中的自动绑定规则

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，可以通过其他方式:
  • 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 路径下的 `Lib\site-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 的自动绑定原理有所帮助。