VSCode 使用 EmmyLua 对lua进行调试

时间：2024年10月
其他：win10，EmmyLua v0.8.20

参考：https://blog.csdn.net/ShenHaoDeHao/article/details/140268354

有几个概念搞清楚就好理解了。一般开发中，我们编写的lua文件由宿主程序的来解析、执行；当然对于我们写的单个的测试文件，我们直接使用 lua.exe test.lua 运行即可，这里可以认为lua.exe 就是宿主程序。

EmmyLua 通过在lua代码中加载 emmy_core.dll到宿主程序中，并启动调试内核代码。调试内核通过socket与VSCode侧连互通;通信有Server端和Client端角色之分。默认情况下：

IDE connect Debugger 即被调试的程序充当Server端，这时被调试的程序应先启动，再启动IDE侧的调试功能连接到调试内核

另外一种就是：

Debugger connect IDE 即IDE充当Server侧，这时应先启动IDE侧的调试功能，等待被调试的程序启动并主动连接到IDE

我们做个简单的测试，在vscode的搜索、安装EmmyLua扩展。我们新建一个testLua文件夹，拖入vscode中打开，新建hello.lua文件：

lua">print("hello!")

点击vscode 右上角的 Toggle Panel ，IDE下方切换到终端页签，输入 lua .\hello.lua ，回车，发现可以打印出“hello!”。
在这里插入图片描述
如果报错，找不到lua，网上搜索安装lua for windows 即可。

接下来进行调试前，我们要在lua代码中引入 EmmyLua 的 Debug 代码。 ctrl + p打开搜索输入>EmmyLua,选择Insert Emmy Debugger Code，然后根据宿主程序需要选择 x86/x64即可(我这里选择x86,选完后运行如果有问题就修改插入代码的路径试试另外一个)：
在这里插入图片描述

插入后代码如下：

lua">package.cpath = package.cpath .. ";c:/Users/xxxx/.vscode/extensions/tangzx.emmylua-0.8.20-win32-x64/debugger/emmy/windows/x86/?.dll"
local dbg = require("emmy_core")
dbg.tcpListen("localhost", 9966)print("hello!")

可以看到这里有个tcpListen，说明lua代码这边是Server端，IDE进行调试时lua代码的宿主程序需要处于运行状态，一般在游戏开发中没有问题，但是我们的测试代码很快就运行完成并退出了，所以我们这里使用【Debugger connect IDE】的方式：这里的tcpListen 改成 tcpConnect。

我们按照下图步骤生成launch.json文件：

我们需要把这个文件里的ideConnectDebugger值改成false：
在这里插入图片描述
接下来就可以调试了，我们在 print("hello!") 前打断点，按F5启动调试器，再在终端页签，输入 lua .\hello.lua 执行即可命中断点：

EmmyLua 还有许多其他功能，需要注意的是EmmyLua为了支持其他IDE，大部分的配置文件需要配置在项目的工作区顶层目录的.emmyrc.json中，具体的配置说明如下：

{"completion": {"autoRequire": true,"autoRequireFunction": "require","autoRequireNamingConvention": "camelCase","callSnippet": false,"postfix": "@"},"signature": {"detailSignatureHelper": false},"diagnostics": {"disable": [],"globals": [],"globalsRegex": [],"severity": {},"enables": []},"hint": {"paramHint": true,"indexHint": true,"localHint": true,"overrideHint": true},"runtime": {"version": "Lua5.4","requireLikeFunction": [],"frameworkVersions": [],"extensions": [],"requirePattern": []},"workspace": {"ignoreDir": [],"ignoreGlobs": [],"library": [],"workspaceRoots": [],"preloadFileSize": 1048576,"encoding": ""},"resource": {"paths": []},"codeLens": {"enable": true},"strict": {"requirePath": false,"typeCall": true}
}

completion

autoRequire: 是否自动补全 require 语句，默认为 true。
autoRequireFunction: 自动补全 require 语句时使用的函数名，默认为 require。
autoRequireNamingConvention: 自动补全 require 语句时使用的命名规范，默认为 camelCase, 可选值为 camelCase, snakeCase, pascalCase。
callSnippet: 是否使用代码片段补全函数调用，默认为 false。
postfix: 补全时的后缀，默认为 @。但是设置该选项暂时无用

signature

detailSignatureHelper: 是否显示详细的函数签名帮助，默认为 false。

diagnostics

disable: 禁用的诊断信息列表, 如果需要工作区内禁用一些诊断消息, 需要填上对应诊断的id, 例如: “undefined-global”
globals: 全局变量列表, 在该列表中的全局变量不会被诊断为未定义.
globalsRegex: 全局变量正则表达式列表, 符合正则表达式的全局变量不会被诊断为未定义.
severity: 诊断消息的严重程度, 例如: “undefined-global”: “warning”, 可选值为 “error”, “warning”, “information”, “hint”.
enables: 启用的诊断信息列表, 语言服务的诊断不是全部都启用的, 可以通过该选项启用一些诊断消息. 例如: “undefined-field”

hint

paramHint: 是否显示参数提示，默认为 true。
indexHint: 在索引表达式跨行时, 是否显示hint，默认为 true。
localHint: 是否显示局部变量提示，默认为 true。
overrideHint: 是否显示重载提示，默认为 true。

runtime

version: 运行时版本, 默认为 Lua5.4, 可选值为 Lua5.1, Lua5.2, Lua5.3, Lua5.4, LuaJIT.
requireLikeFunction: 类似 require 的函数列表, 用于识别类似 require 的函数, 例如: [“import”].
frameworkVersions: 框架版本列表, 用于识别框架版本, 例如: [“love2d”]. 可以和emmylua doc 的version标签配合使用.
extensions: 文件扩展名列表, 用于识别文件扩展名, 例如: [“.lua”, “.lua.txt”].
requirePattern: require 模式列表, 该参数和lua中的package.path和package.cpath有关, 例如: [“?.lua”, “?.lua.txt”]. 默认不需要填写, 将自动拥有, [“?.lua”, “?/init.lua”].

workspace

工作区配置, 大部分工作区配置本身既支持相对路径也支持绝对路径

ignoreDir: 忽略的目录列表, 用于忽略一些目录, 例如: [“build”, “dist”].
ignoreGlobs: 忽略的文件列表, 基于正则表达式的忽略一些文件, 例如: [“.log", ".tmp”].
library: 库文件目录列表, 用于指定一些库文件, 例如: [“/usr/local/lib”].
workspaceRoots: 工作区根目录列表, 用于指定工作区的根目录, 例如: [“Assets/script/Lua”]. 该功能主要是为了让require正常工作, 如果必须要打开lua主目录的上级目录, 需要在这里添加当前打开的目录相对于lua主目录的相对路径.
preloadFileSize: 预加载文件大小, 默认为 1048576 字节, 用于控制预加载文件的大小.
encoding: 文件编码, 默认为 utf-8, 用于读取文件时的编码.

resource

paths: 资源路径列表, 用于指定需要加载的资源的根目录, 例如: [“Assets/settings”]. 其默认值为当前打开的工作区目录, emmylua支持在任意字符串中的文件路径补全, 以及任意字符串中的文件路径跳转. 通过配置这个目录, 可以让emmylua知道哪些目录是资源目录, 从而正确的提供补全和跳转.

codeLens

enable: 是否启用CodeLens功能, 默认为 true.

strict

requirePath: 是否启用require严格模式, 默认为 true. 严格模式时, require必须从指定的根目录开始, 否则无法跳转
typeCall: 是否启用类型调用时严格模式, 默认为 true. 严格模式时, 类型调用必须手动写好重载, 否则返回unknown, 非严格模式时, 类型调用会返回自身