简介

从 Cocos Creator 3.7.0 开始，我们将生成 JS 绑定代码的方式从 bindings-generator 改为 Swig。 Swig 通过解析与 C++ 兼容的接口定义语言 (IDL) 的方式来生成胶水代码，此方式有较多好处 。 关于我们为什么改用 Swig，可以参考此 issue。

为引擎模块生成绑定代码

在 3.8 及以上的版本中，开发者不再需要手动触发绑定代码的生成，因为 CMake 会自动在编译过程中调用 SWIG 命令来生成绑定代码。如果生成失败, 请注意终端的输出日志。

需要注意: 如果为引擎添加或删除了 .i 文件，你需要重新生成工程来确保更新对 .i 文件的引用，并生成更新的绑定代码。

为开发者的项目生成绑定代码

  • 确保你已经安装了 NodeJS，版本号大于或等于 v8.9.4

  • 打开终端 ( macOS / Linux) 或者命令提示符 ( Windows ),

  • 创建一个用于存放自动绑定胶水代码的目录，例如： /Users/abc/my-project/native/engine/common/Classes/bindings/auto

  • 写一个 JS 配置文件

    • 创建一个 JS 配置文件, 路径例如： /Users/abc/my-project/tools/swig-config/swig-config.js ，内容为：

      1. 'use strict';
      2. const path = require('path');
      4. // 开发者自己的模块定义配置
      5. // configList 是必须的
      6. const configList = [
      7.   [ 'your_module_interface_0.i', 'jsb_your_module_interface_0_auto.cpp' ],
      8.   [ 'your_module_interface_1.i', 'jsb_your_module_interface_1_auto.cpp' ],
      9.   // ......
      10. ];
      12. const projectRoot = path.resolve(path.join(__dirname, '..', '..'));
      13. // interfaceDir 是可选的
      14. const interfacesDir = path.join(projectRoot, 'tools', 'swig-config');
      15. // bindingsOutDir 是可选的
      16. const bindingsOutDir = path.join(projectRoot, 'native', 'engine', 'common', 'Classes', 'bindings', 'auto');
      18. module.exports = {
      19.   interfacesDir, // 可选参数, 如果没有指定，configList 中的路径必须为绝对路径或者相对于当前 swig-config.js 的相对路径
      20.   bindingsOutDir, // 可选参数，如果没有指定, configList 中的路径必须为绝对路径或者相对于当前 swig-config.js 的相对路径
      21.   configList // 必填参数
      22. };

    • 执行如下命令

      1. # 如果当前终端或者命令提示符所在的目录不是在 '/Users/abc/my-project/tools/swig-config'
      2. $ node < 引擎的根目录 >/native/tools/swig-config/genbindings.js -c /Users/abc/my-project/tools/swig-config/swig-config.js
      1. # 如果你已经在 '/Users/abc/my-project/tools/swig-config' 目录, 你执行命令的时候可以不需要带上 -c 参数，例如：
      2. $ cd /Users/abc/my-project/tools/swig-config
      3. $ node < 引擎的根目录 >/native/tools/swig-config/genbindings.js

Swig 接口定义文件

  • 在引擎的 engine/native/tools/swig-config 目录下有一个 swig-interface-template.i 模版文件。你可以拷贝其到自己的工程目录下并重命名。此模版文件中包含一些注释用于展示如何在 .i 文件中配置你的模块。你也可以参考在 engine/native/tools/swig-config 目录下引擎内部的 .i 文件，例如：参考 scene.i 或者 assets.i 来快速上手。
  • 如果你使用 Visual Studio Code, 你可以安装 Hong-She Liang 开发的 SWIG Language 扩展，其可用于 .i 文件的语法高亮。
  • 关于编写 .i 文件的更多详细信息，建议参考下面 教程 章节。

教程

请访问 在 Cocos Creator 中的 Swig 工作流教程, 其包含如何一步一步地为引擎内的新模块或用户工程模块配置绑定。