导出C/C++API给Lua使用

最新推荐文章于 2021-05-21 16:54:18 发布

lhj190506206

最新推荐文章于 2021-05-21 16:54:18 发布

阅读量1.6k

点赞数

分类专栏： cocos2d-x

cocos2d-x 专栏收录该内容

7 篇文章 0 订阅

订阅专栏

cocos2d-x 和 quick-cocos2d-x 的底层代码都是使用 C++ 语言开发的。为了使用 Lua 脚本语言进行开发，我们利用 tolua++ 工具，将大量的 C/C++ API 导出到了 Lua 中。

使用 tolua++ 的基本步骤：

从 C/C++ 源代码复制头文件的内容到 .tolua（tolua++ 文档中称为 .pkg）文件中。
修改 .tolua 文件内容，去掉 tolua++ 无法识别的内容，以及不需要导出到 Lua 的定义。
运行 tolua++ 工具，根据 .tolua 文件生成 luabinding 接口文件（由 .cpp 文件和 .h 文件自称）。
在 AppDelegate.cpp 中加载 luabinding 文件。
在 AppDelegate 初始化 Lua 虚拟机后，调用 luabinding 接口文件中的 luaopen 函数，注册 C/C++ API。

根据实践，我们建议采用如下的方案来完成整个导出工作。

从 C/C++ 源文件创建 .tolua 文件

假设我们的 MyClass.h 头文件内容如下：

 
   01. 
   #ifndef __MY_CLASS_H_ 
  
   02. 
   #define __MY_CLASS_H_ 
  
   03. 
     
   04. 
   class MyClass 
  
   05. 
   { 
  
   06. 
   public: 
  
   07. 
   static void addTwoNumber(float number1, float number2); 
  
   08. 
     
   09. 
   private: 
  
   10. 
   MyClass(void) {} 
  
   11. 
   }; 
  
   12. 
     
   13. 
   #endif // __MY_CLASS_H_

为了便于维护，应该将 .h 文件对应的 tolua 命名为 XXX_luabinding.tolua。这样生成的 luabinding 接口文件名就是 XXX_luabinding.cpp 和 XXX_luabinding.h，不会和已有的 C/C++ 源文件冲突。

创建 MyClass_luabinding.tolua 文件，并修改内容为：

 
   1. 
   class MyClass 
  
   2. 
   { 
  
   3. 
   public: 
  
   4. 
   static void addTwoNumber(float number1, float number2); 
  
   5. 
   };

这里可以看到 .tolua 的内容有明显简化。详细的内容修改规则，会在本文后续部分说明。

生成 luabinding 接口文件

quick 为了简化这一步工作，提供了相应工具，我们只需要创建一个脚本文件来调用工具即可。

创建 build_luabinding.sh 文件，内容如下：

 
   1. 
   #!/usr/bin/env bash 
  
   2. 
   DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &amp;&amp; pwd )" 
  
   3. 
   cd "$DIR" 
  
   4. 
   OUTPUT_DIR="$DIR" 
  
   5. 
   MAKE_LUABINDING="$QUICK_COCOS2DX_ROOT"/bin/compile_luabinding.sh 
  
   6. 
   $MAKE_LUABINDING -d "$OUTPUT_DIR" MyClass_luabinding.tolua

记得在命令行中 chmod 755 build_luabinding.sh，否则无法执行该脚本。

Windows 版的批处理内容如下：

 
   1. 
   @echo off 
  
   2. 
   set DIR=%~dp0 
  
   3. 
   set OUTPUT_DIR=%DIR% 
  
   4. 
   set MAKE_LUABINDING="%QUICK_COCOS2DX_ROOT%\\bin\\compile_luabinding.bat" 
  
   5. 
   pushd 
  
   6. 
   cd "%DIR%" 
  
   7. 
   call %MAKE_LUABINDING% -d %OUTPUT_DIR% MyClass_luabinding.tolua

注意：运行脚本前请确保已经下载了 quick-cocos2d-x，并且正确设置了 QUICK_COCOS2DX_ROOT 环境变量。环境配置请参考《入门指引》。
在命令行下运行我们创建的脚本，如果一切顺利，我们会看到如下输出信息：

 
   01. 
   creating file: MyClass_luabinding.cpp 
  
   02. 
   creating file: MyClass_luabinding.h 
  
   03. 
     
   04. 
   // add to AppDelegate.cpp 
  
   05. 
   #include "MyClass_luabinding.h" 
  
   06. 
     
   07. 
   // add to AppDelegate::applicationDidFinishLaunching() 
  
   08. 
   CCLuaStack* stack = CCScriptEngineManager::sharedManager() 
  
   09. 
   ->getScriptEngine() 
  
   10. 
   ->getLuaStack(); 
  
   11. 
   lua_State* L = stack->getLuaState(); 
  
   12. 
   luaopen_MyClass_luabinding(L);

载入 luabinding 接口文件

打开我们的项目，将 MyClass_luabinding.cpp 和 MyClass_luabinding.h 文件加入工程。然后修改 AppDelegate.cpp 文件：

在 AppDelegate.cpp 头部区域添加：

#include "MyClass_luabinding.h"

在 AppDelegate::applicationDidFinishLaunching() 函数内添加：

luaopen_MyClass_luabinding(L);

注意这一行代码应该添加在其他 luaopen 函数后面，例如：

 
   01. 
   // register lua engine 
  
   02. 
   CCLuaEngine *pEngine = CCLuaEngine::defaultEngine(); 
  
   03. 
   CCScriptEngineManager::sharedManager()->setScriptEngine(pEngine); 
  
   04. 
     
   05. 
   CCLuaStack *pStack = pEngine->getLuaStack(); 
  
   06. 
   lua_State* L = pStack->getLuaState(); 
  
   07. 
     
   08. 
   // load lua extensions 
  
   09. 
   luaopen_lua_extensions(L); 
  
   10. 
   // load cocos2dx_extra luabinding 
  
   11. 
   luaopen_cocos2dx_extra_luabinding(L); 
  
   12. 
     
   13. 
   // thrid_party 
  
   14. 
   luaopen_third_party_luabinding(L); 
  
   15. 
     
   16. 
   // CCBReader 
  
   17. 
   tolua_extensions_ccb_open(L); 
  
   18. 
     
   19. 
   // MyClass 
  
   20. 
   luaopen_MyClass_luabinding(L);

应该将我们的代码追加到 tolua_extensions_ccb_open() 后面。

经过上述修改后，重新编译运行项目应该就可以在 Lua 脚本中使用我们导出的 MyClass 对象极其方法了。

.tolua 文件内容的修改规则

前面的 MyClass 是一个非常简单的例子，但我们实际游戏中的 C/C++ API 可能比较复杂。在修改 .tolua 文件内容时，应该仔细阅读以下内容。

删除所有无需在 Lua 中使用的内容

导出的 API 越多，在 Lua 虚拟机中占用的符号表空间就越多。因此我们第一步要做的就是删除所有无需在 Lua 中使用的内容。

对于 enum、宏定义，如果需要导出，原文保留即可。但宏定义只能导出数值定义，例如：

1. #define kCCHTTPRequestMethodGET 0

2. #define kCCHTTPRequestMethodPOST 1

而非数值的宏定义无法导出，以下内容会导出失败：

1. #define kMyConstantString "HELLO"

删除所有无法识别的宏，例如 CC_DLL。
删除 C++ class 中所有非 public 的定义。
删除 C++ class 中的类成员变量。
删除 inline 关键词，以及 inline function 的实现，只保留声明。

展开宏

有些宏是不能直接删除的，例如 CC_PROPERTY。对于这类宏，需要根据宏定义，将宏展开为声明。

CC_PROPERTY(float, m_fDuration, Duration)

展开为：

1. float getDuration();

2. void setDuration(float v);

需要如此处理的宏包括：CC_PROPERTY_READONLY, CC_PROPERTY, CC_PROPERTY_PASS_BY_REF, CC_SYNTHESIZE_READONLY, CC_SYNTHESIZE_READONLY_PASS_BY_REF, CC_SYNTHESIZE, CC_SYNTHESIZE_PASS_BY_REF, CC_SYNTHESIZE_RETAIN。

幸运的是这些宏大多只用在 cocos2d-x 基础代码里，我们自己的 C++ class 还是不要用这些宏了。