更新文档

pangweiwei · Oct 10, 2019 · a6e7961 · a6e7961
1 parent bebb46f
commit a6e7961
Show file tree

Hide file tree

Showing 7 changed files with 125 additions and 64 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,11 @@
+## 2.3.0
+
++ 增加了自动路径识别功能
++ 支持在cocos2dx下的c库引用
++ 修复了开始运行时step不正常，lua后缀替换异常的bug
+
+
+
 ## 2.2.1
 
 + 修复了单文件调试 文件路径中的 \ 被当做转义符的问题

diff --git a/Debugger/LuaPanda.lua b/Debugger/LuaPanda.lua
@@ -415,7 +415,7 @@ function this.doctor()
                     if isAbsolutePath then
                         strTable[#strTable + 1] = "\n说明:从lua虚拟机获取到的是绝对路径，format使用getinfo路径。";
                     else
-                        strTable[#strTable + 1] = "\n说明:从lua虚拟机获取到的是相对路径，format来源于cwd+getinfo拼接。";
+                        strTable[#strTable + 1] = "\n说明:从lua虚拟机获取到的是相对路径，调试器运行依赖的绝对路径(format)是来源于cwd+getinfo拼接。";
                     end
                     strTable[#strTable + 1] = "\nfilepath是VSCode通过获取到的文件正确路径 , 对比format和filepath，调整launch.json中CWD，或改变VSCode打开文件夹的位置。使format和filepath一致即可。\n如果format和filepath路径仅大小写不一致，设置launch.json中 pathCaseSensitivity:false 可忽略路径大小写";
                 end
@@ -485,7 +485,7 @@ function this.getInfo()
         if isAbsolutePath then
             strTable[#strTable + 1] = "\n说明:从lua虚拟机获取到的是绝对路径，format使用getinfo路径。" .. winDiskSymbolTip;
         else
-            strTable[#strTable + 1] = "\n说明:从lua虚拟机获取到的是相对路径，format来源于cwd+getinfo拼接。如format文件路径错误请尝试调整cwd或改变VSCode打开文件夹的位置。也可以在format对应的文件下打一个断点，调整直到format和Breaks Info中断点路径完全一致。" .. winDiskSymbolTip;
+            strTable[#strTable + 1] = "\n说明:从lua虚拟机获取到的路径(getinfo)是相对路径，调试器运行依赖的绝对路径(format)是来源于cwd+getinfo拼接。如format路径错误请尝试调整cwd或改变VSCode打开文件夹的位置。也可以在format对应的文件下打一个断点，调整直到format和Breaks Info中断点路径完全一致。" .. winDiskSymbolTip;
         end
     else
         strTable[#strTable + 1] = "\n说明:已开启autoPathMode自动路径模式，调试器会根据getinfo获得的文件名自动查找文件位置，请确保VSCode打开的工程中不存在同名lua文件。";

diff --git a/Docs/Manual/access-guidelines.md b/Docs/Manual/access-guidelines.md
@@ -14,23 +14,42 @@ lua调试器依赖于 **luasocket** 和 **规范的路径**，需验证这两点
 
 
 
+### 第二步 路径说明
 
-### 第二步 路径规范
+**2.3.0增加了自动路径模式。开启后调试器会自动处理路径。用户只需保证VSCode打开的目录中不存在同名lua文件即可。当开启自动路径模式后，可跳过本节继续接入。**
 
-调试器运行需要从lua虚拟机中获取当前文件信息。所以要求工程debug.getinfo或debug.traceback能输出较为规范的路径，就是**绝对路径**或者**对于固定位置的相对路径**。目前的slua, xlua, slua-unreal框架都已经支持这个特性。但还是建议初期接入时做一下测试。
+launch.json文件中配置项 `"autoPathMode": true/false` 可以设置是否使用自动路径，无此配置项时默认关闭。
+
+#### 关于自动路径配置和手动配置的说明：
+
+调试器需要获得当前执行文件的绝对路径，以便做断点匹配和命中断点后打开对应文件。但是通过getinfo从lua虚拟机获取的路径可能是一个相对路径 ，调试器要把它转化为绝对路径。
+
+把相对路径转为绝对路径的方式有以下两种:
+
+1. 自动路径模式
+
+自动路径处理，原理是VSCode端在启动时扫描当前工程中的lua文件，创建[文件路径表]。当需要绝对路径时，把从 getinfo 获得的非完整路径在[文件路径表]中查询 ，就可以获得绝对路径。这种路径策略易于配置使用，也有利于真机调试。因为[文件路径表]的查询key是文件名，所以需要用户保证工程中不存在同名lua文件，否则断点可能会指向错误。
+
+2. 拼接路径模式
+
+本模式下会使用 cwd+getinfo 和 VSCode 传来的断点路径作对比，完全一致才算命中。这种策略比较准确，不会受到同名文件的干扰，但是配置较麻烦。如果希望手动配置路径或了解处理的细节，请继续阅读。
+
+调试器运行需要从lua虚拟机中获取当前文件信息。所以要求工程debug.getinfo或debug.traceback能输出较为规范的路径，就是**绝对路径**或者**对于固定位置的相对路径**。
 
 **测试方法**：在代码中加入`print(debug.traceback("debug test"))`, 查看打印的堆栈。
 
 如下打印出文件的绝对路径，可以进行下一步
 ![absolute_path](../static/access_introduction/absolute_path.png)
 
-打印出的信息是一个相对路径(路径前可能带有@)，可进行下一步
+打印出的信息是一个相对路径(路径前可能带有@)，这不会影响调试器工作，可进行下一步
 ![relatively_path](../static/access_introduction/relatively_path.png)
 
 打印出的路径包含在[string ]中，只要是符合上面的要求，是一个可以定位的路径，可进行下一步
 ![string_path](../static/access_introduction/string_path.png)
 
-下面案例测试不通过，原因是仅输出了文件名，而这些文件其实不在同一个目录下。调试器无法仅根据文件名确定文件位置。
+
+
+如果仅输出了文件名，而这些文件其实不在同一个目录下，如下面的案例。此时需要调试器根据文件名定位文件路径，必须开启自动路径功能（ launch.json 中设置 autoPathMode:true ），否则无法正常工作。
 
 ![filename_path](../static/access_introduction/filename_path.png)
 
@@ -54,15 +73,15 @@ lua调试器依赖于 **luasocket** 和 **规范的路径**，需验证这两点
 
 文件：`LuaPanda.lua`, `DebugTools.lua`
 
-下载位置：本git项目的 `Debugger` 目录下
+下载位置：github 的 `Debugger` 目录下
 
-把以上两个文件放在lua代码可以引用到的位置，并在用户代码中引用。
+把以上两个文件放在lua代码可以引用到的位置，并在用户代码中引用:
 
 ```
 require("LuaPanda").start("127.0.0.1",8818);
 ```
 
-*8818是默认端口号，如果需要修改，请同时修改launch.json的设置。
+*8818是默认端口号，如果需要修改，请同时修改launch.json的端口设置。
 
 
 
@@ -77,15 +96,16 @@ require("LuaPanda").start("127.0.0.1",8818);
 切换到VSCode的**调试选项卡**，点击齿轮，在弹出框中选择 LuaPanda (若无此选项说明以前用别的插件调试过lua , 要把先前用过的调试插件禁用)。会自动生成launch.json文件。
 ![vscode_debug_ui](../static/access_introduction/vscode_debug_ui.png)
 
-launch.json 配置项中要修改的主要是luaFileExtension, 改成lua文件使用的后缀就行。（比如xlua改为lua.txt, slua是txt），如果保持为空则尝试自动获取。
-各配置项鼠标悬停会有提示，可根据需要更改。
+launch.json 配置项中要修改的主要是luaFileExtension, 改成lua文件使用的后缀就行。（比如xlua改为lua.txt, slua是txt）。**各配置项鼠标悬停会有提示**，可根据需要更改。
 ![debug_config](../static/access_introduction/debug_config.png)
 
 
 
 **注：调试时提示找不到文件的处理**
 
-上面配置项中的`cwd`，其默认值`${workspaceFolder}`。${workspaceFolder}指的是VScode打开文件夹的路径。
+如果是自动路径模式，请检查lua后缀是否配置正确，以及VSCode打开的工程是否正确。
+
+如果是手动路径模式，请按如下步骤：
 
 如果开始调试时弹出了如下错误
 
@@ -103,8 +123,6 @@ format是调试器拼接出的文件路径，filepath是文件真实存在的路
 
 
 
-
-
 ### 第三步 开始调试
 
 **先运行VSCode端，再运行Lua代码**: 点击调试选项卡左上角的绿色箭头，再运行unity/ue4工程。如果有stopOnEntry或是执行到断点处，就会自动停住。

diff --git a/Docs/Manual/debug-on-phone.md b/Docs/Manual/debug-on-phone.md
@@ -60,31 +60,38 @@ require("LuaPanda").start("pcIP"，8818)
 
 ### 关于真机调试的说明
 
-+ 当调试lua文件时，当前正在执行的文件路径是由lua虚拟机返回给调试器([http://www.lua.org/manual/5.3/manual.html#lua_getinfo](http://www.lua.org/manual/5.3/manual.html#lua_getinfo))。
++ 安卓手机连接windows开启反向代理后，游戏运行会因为attach连接而卡顿。建议准备进行连接时再开反向代理，不需要调试时拔线或者使用下面命令解除反向代理
 
-  调试器获得的路径可能是文件的绝对路径，也可能是相对路径。这取决于加载文件时传给lua虚拟机的文件路径。
+  ```
+  adb reverse --remove-all
+  ```
 
-  如果调试器获得的是绝对路径，那么在命中断点时直接把这个路径传给VSCode。
+  mac上无此现象。
 
-  如果是相对路径，调试器使用cwd+getinfo拼出完整路径，再传给VSCode。可以调整cwd，以确保拼出的路径是正确的。
 
-+ 如果调试器获得的绝对路径，或者拼接成的路径有偏差（参见 [issue #18](https://github.com/Tencent/LuaPanda/issues/18)），我们提供路径映射配置 docPathReplace
 
-  比如lua文件在pc上路径 		 C:/GameProcect/Assets/script/test.lua
-  放置在手机里，路径变成了 	/data/data/com.project.test/script/test.lua
+### 真机调试时的路径说明
 
-  在launch.json docPathReplace中设置
++ 自动路径模式下，无需特别设置。
++ 如使用手动拼接路径，请参阅如下内容决定是否使用路径映射
 
-  ```json
-  "docPathReplace": ["/data/data/com.project.test/"," C:/GameProcect/Assets/"]
-  ```
+当调试lua文件时，当前正在执行的文件路径是由lua虚拟机返回给调试器([http://www.lua.org/manual/5.3/manual.html#lua_getinfo](http://www.lua.org/manual/5.3/manual.html#lua_getinfo))。
 
-  就可以完成路径映射，把运行环境的/data/data/com.project.test/script/test.lua映射到观察环境C:/GameProcect/Assets/script/test.lua
+调试器获得的路径可能是文件的绝对路径，也可能是相对路径。这取决于加载文件时传给lua虚拟机的文件路径。
 
-+ 安卓手机连接windows开启反向代理后，游戏运行会因为attach连接而卡顿。建议准备进行连接时再开反向代理，不需要调试时拔线或者使用下面命令解除反向代理
+如果调试器获得的是绝对路径，那么在命中断点时直接把这个路径传给VSCode。
 
-  ```
-  adb reverse --remove-all
-  ```
+如果是相对路径，调试器使用cwd+getinfo拼出完整路径，再传给VSCode。可以调整cwd，以确保拼出的路径是正确的。
+
+如果调试器获得的绝对路径，或者拼接成的路径有偏差（参见 [issue #18](https://github.com/Tencent/LuaPanda/issues/18)），我们提供路径映射配置 docPathReplace
+
+比如lua文件在pc上路径 		 C:/GameProcect/Assets/script/test.lua
+放置在手机里，路径变成了 	/data/data/com.project.test/script/test.lua
+
+在launch.json docPathReplace中设置
+
+```json
+"docPathReplace": ["/data/data/com.project.test/"," C:/GameProcect/Assets/"]
+```
 
-  mac上无此现象。
+就可以完成路径映射，把运行环境的/data/data/com.project.test/script/test.lua映射到观察环境C:/GameProcect/Assets/script/test.lua
diff --git a/Docs/Manual/quick-use.md b/Docs/Manual/quick-use.md
@@ -6,39 +6,59 @@
 
 ### console
 
-使用console调试请先确认安装了luasocket。windows下调试console中lua进程, 请调整launch.json中useCHook: false(见附录)
+使用console调试请先确认安装了luasocket。
 
-验证luasocket方法：console下执行lua，并 `require "socket.core"` 不报错说明已安装luasocket。
+验证方法：console下执行lua，并 `require "socket.core"` 不报错说明已安装luasocket。
 
 1. **安装VSCode插件**：VSCode 商店搜索 LuaPanda，安装插件。
-2. **添加被调试文件**：创建一个文件夹，名为`luaDebugTest`，  其中放入被调试lua文件。
-3. **配置**：使用VSCode 打开 `luaDebugTest` 文件夹，切换到调试页卡（shitf + cmd(ctrl) + D），点击页面内的齿轮符号，选择 LuaPanda，会自动生成一张配置表。检查配置表中的"luaPath", 填入lua.exe位置。
-4. **开始调试**：  **代码编辑面板中点开要调试的文件**，配置项选择`LuaPanda-DebugFile`，点击VSCode调试页卡下的绿色箭头，VSCode会拉起terminal ,并执行命令调试运行当前窗口的lua。VSCode有时会报窗口错误，请选择正确的文件，重复步骤4即可。
+
+2. **添加被调试文件**：创建一个文件夹，取名为`LuaPandaTest`，  其中放入被调试lua文件。
+
+3. **配置**：使用 VSCode 打开 `LuaPandaTest` 文件夹，切换到调试页卡（shitf + cmd(ctrl) + D），点击页面内的齿轮符号，选择 LuaPanda，会自动生成一张配置表。
+
+   如果仅在指定目录下可以调用lua命令，需修改配置表中的"luaPath",  填入lua.exe位置。
+
+4. **开始调试**：  **代码编辑面板中点开要调试的文件**，VSCode切换到调试选项卡，配置项选择`LuaPanda-DebugFile`，点击VSCode调试页卡下的绿色箭头，VSCode会拉起terminal ,并执行命令调试运行当前窗口的lua。
+
+   如出现错误，可检查当前激活的窗口是否正确，luaPath配置是否正确。
 
 
 
 ### slua
 
 1. **下载 slua 工程** 下载 slua 工程源码 https://github.com/pangweiwei/slua
 2. **slua 工程设置** 使用 Unity 打开 slua 工程，切换工程平台到 Android/iOS ， 点击菜单 Slua -> All -> Make，选择 `Slua/Editor/example/Circle` 场景。
-3. **放入调试文件** 把`/Debugger`中的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到slua工程 `Slua/Resources/` 目录下, 并修改文件后缀为 `.txt`
+3. **放入调试文件** 把github中 /Debugger 下的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到slua工程 `Slua/Resources/` 目录下, 并修改文件后缀为 `.txt`
 4. **配置工程** VSCode 打开 `Slua/Resources/` 目录，点击 VSCode 调试选项卡下的齿轮图标，选择 LuaPanda。把配置项 luaFileExtension 值修改为 "txt"。
-5. **开始调试** 在 `Slua/Resources/circle/circle.txt` 中加入代码 `require("LuaPanda").start("127.0.0.1",8818)`.  配置项选择`LuaPanda`，点击 VSCode 调试的绿色箭头，再运行Unity，在加入 require 的位置后会自动停止。也可以打断点调试
+5. **开始调试** 在 `Slua/Resources/circle/circle.txt` 中加入代码 `require("LuaPanda").start("127.0.0.1",8818)`.  VSCode切换到调试选项卡，配置项选择`LuaPanda`，点击 VSCode 调试的绿色箭头，再运行Unity，在加入 require 的位置后会自动停止。也可以打断点调试
 
 
 
 ### xlua
 
 1. **下载 xlua 工程**  https://github.com/Tencent/xLua
-2. **放入调试文件** 把/Debugger中的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到xlua工程 `\XLua\Examples\07_AsyncTest\Resources` 目录下, 并修改后缀为 `.lua.txt`
+2. **放入调试文件** 把github中 /Debugger 下的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到xlua工程 `\XLua\Examples\07_AsyncTest\Resources` 目录下, 并修改后缀为 `.lua.txt`
 3. **配置工程**  把`\XLua\Examples\07_AsyncTest\Resources` 文件夹放入 VSCode , 点击 VSCode 调试选项卡下的齿轮图标，选择 LuaPanda。把配置项 luaFileExtension 值修改为 "lua.txt"
-4. **开始调试** 在`\XLua\Examples\07_AsyncTest\Resources\async_test.lua.txt` 中加入`require("LuaPanda").start("127.0.0.1",8818)` 。配置项选择`LuaPanda`, 点击 VSCode 的开始调试箭头，运行Unity，在加入 require 的位置后会自动停止。也可以打断点调试。
+4. **开始调试** 在`\XLua\Examples\07_AsyncTest\Resources\async_test.lua.txt` 中加入`require("LuaPanda").start("127.0.0.1",8818)` 。VSCode切换到调试选项卡，配置项选择`LuaPanda`, 点击 VSCode 的开始调试箭头，运行Unity，在加入 require 的位置后会自动停止。也可以打断点调试。
 
 
 
 ### slua-unreal
 
 1. **下载slua-unreal工程** https://github.com/Tencent/sluaunreal
-2. **放入调试文件** 把/Debugger中的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到slua-unreal 工程`sluaunreal/Content/Lua/`目录下
+2. **放入调试文件** 把github中 /Debugger 下的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到slua-unreal 工程`sluaunreal/Content/Lua/`目录下
 3. **配置工程** 把`sluaunreal/Content`文件夹放入 VSCode , 点击 VSCode 调试选项卡下的齿轮图标，选择 LuaPanda。
-4. **开始调试** 在执行的lua代码中加入`require("LuaPanda").start("127.0.0.1",8818)` 。配置项选择`LuaPanda`， 点击 VSCode 的开始调试箭头，再运行ue4，在加入 require 的位置后会自动停止。之后可以打断点调试。
+4. **开始调试** 在执行的lua代码中加入`require("LuaPanda").start("127.0.0.1",8818)` 。VSCode切换到调试选项卡，配置项选择`LuaPanda`， 点击 VSCode 的开始调试箭头，再运行ue4，在加入 require 的位置后会自动停止。之后可以打断点调试。
+
+
+
+#### cocos2dx
+
+可能存在的问题：LuaPanda目前支持标准lua虚拟机，cocos2dx集成的是luajit，可能会在调试函数尾调用时出现跳步的情况，后续完整支持luajit后会解决此问题。
+
+1. 下载cocos2dx并创建新工程 
+
+2. **放入调试器文件** 把github中 /Debugger 下的 `LuaPanda.lua, DebugTools.lua` 两个文件拷贝到cocos2dx工程 /src下，和main.lua 文件同级
+3. **配置工程** 把`src`文件夹拖入 VSCode , 点击 VSCode 调试选项卡下的齿轮图标，选择 LuaPanda。
+
+4. **开始调试** 在main.lua文件 `require "cocos.init"` 行之前加入代码    `require("LuaPanda").start("127.0.0.1",8818)` 。VSCode切换到调试选项卡，配置项选择`LuaPanda`， 点击 VSCode 的开始调试箭头，再运行cocos2dx工程，在加入 require 的位置后会自动停止。之后可以打断点调试。