docs(debug): add main process debugging document (netless-io#932)

Author: BlackHole1

.commitlintrc.js

@@ -50,6 +50,7 @@ module.exports = {
                 "project",
                 "ide",
                 "license",
+                "debug",
             ],
         ],
         "scope-case": [2, "always", ["lower-case", "kebab-case"]],

README-zh.md

@@ -84,8 +84,9 @@ yarn run start
 
 ## 文档
 
-- [环境变量值参考](docs/env/README-zh.md)
 - [发布版本说明](docs/releases)
+- [环境变量值参考](docs/env/README-zh.md)
+- [调试 Flat](docs/debugging/README-zh.md)
 
 ## 代码贡献者
 

README.md

@@ -85,8 +85,9 @@ Many Flat components UI can be quickly viewed and developed via Storybook ([Onli
 
 ## Documents
 
-- [Environment Variables Reference](docs/env/README.md)
 - [Release Version Description](docs/releases)
+- [Environment Variables Reference](docs/env/README.md)
+- [Debugging Flat](docs/debugging/README.md)
 
 ## Code Contributors
 

cspell.config.js

@@ -103,6 +103,7 @@ module.exports = {
         "webfonts",
         "browserslist",
         "estree",
+        "webstorm",
 
         // CNCF
         "nindent",
@@ -111,7 +112,7 @@ module.exports = {
         "Minikube",
         "tolerations",
         "Kube",
-        "agoraflat"
+        "agoraflat",
     ],
     flagWords: ["fuck", "bitch", "asshole", "bullshit", "crap", "suck", "wtf"],
     dictionaries: [

docs/debugging/README-zh.md

@@ -0,0 +1,5 @@
+## 调试
+
+### Electron
+
+* [主进程 (desktop/main-app)](electron/README-zh.md)

docs/debugging/README.md

@@ -0,0 +1,5 @@
+## Debugging
+
+### Electron
+
+* [Main Process (desktop/main-app)](electron)

docs/debugging/electron/README-zh.md

@@ -0,0 +1,65 @@
+## Electron - 主进程 (desktop/main-app)
+
+为了方便调试，我们给预留的 _Debug_ 配置，都设置了: `--enable-logging` 和 `--inspect=5859`
+
+* `--enable-logging`: 这个选项将会传递给 _Electron_，传递后 _Electron_ 将会把自身的 `debug` 日志打印到当前控制台
+* `--inspect=5859`: 如果你更喜欢使用 _Chrome DevTools_ 进行调试的话，那么你可以在 `chrome://inspect` 监听此端口进行调试
+
+### WebStorm
+
+我们已经在 _WebStorm_ 里帮你设置好了 _Debug Main_ Configurations，你可以直接使用它来进行 _Debug_
+
+> 需要注意的是，你应该选择 `Debug` 按钮，而非 `Run` 按钮，就像下图所示:
+
+> ![webstorm-debug-button](assets/webstorm-debug-button.png)
+
+### vscode
+
+我们也为了 _vscode_ 预留了配置好的 _Debug Main_ configurations，你可以在 _vscode_ 的侧边栏进行 _Debug_
+
+如图所示:
+
+![vscode-debug-button](assets/vscode-debug-button.png)
+
+### 额外说明
+
+### `--enable-logging` 参数
+
+目前我们所使用的 `Electron` 版本并不支持设置日志的输出位置，因为这个特性在 `Electron v14.0.0` 才被支持，有关这一点可以参考: [electron/electron#25089](https://github.com/electron/electron/pull/25089)
+
+未来当 _Flat_ 升级 `Electron` 版本到 _14.0.0_ 或者更高时，我们将进行支持
+
+### `--inspect=5859` 参数
+
+如果你想使用 `Chrome DevTools` 进行调试，可以参考下面的流程:
+
+首先你要先确保你已经启动了 _Debug_，同时也在启动前设置了断点。
+
+当 _Debug_ 启动后，_Node.js_ 会去监听 `5859` 端口。此时在 `Chrome` 地址栏中打开: `chrome://inspect`，就像下面这样
+
+![chrome-inspect-page](assets/chrome-inspect-page.png)
+
+此时点击: _Open dedicated DevTools for Node_，会出现一个 `DevTools` 的窗口
+
+![chrome-inspect-node-devtools](assets/chrome-inspect-node-devtools.png)
+
+此时你的页面可能和我不一致，请不用担心。点击 _Add connection_，在输入框中输入: `localhost:5859`，再点击 _Add_ 就可以进行调试了。就像下面这样：
+
+![chrome-inspect-node-devtools-launch](assets/chrome-inspect-node-devtools-launch.png)
+
+### `Watch` 不一致问题
+
+我们在调试过程中，经常需要使用 `Watch` 的功能，但是需要注意的是，你所 _Watch_ 的 变量可能并不存在。因为 _Debug_ 所执行的代码是编译后的，所以变量名有可能会被重写。
+
+但好消息是，目前发现这种变量重写只影响: `import` 语句，例如:
+
+* `import runtime from "./Runtime"` => `Runtime_1`
+* `import { app } from "electron""` => `electron_1`
+
+用一个截图可以更加清楚的描述这个问题：
+
+![watch-var](assets/watch-var.png)
+
+造成这个问题的原因是因为 `tsc` 的编译，目前还没有更好的办法去解决，只能在操作时注意。
+
+> 即使使用 `ts-node` 作为运行时，也是一样的。因为 `ts-node` 本质也就是动态的去做 `tsc`

docs/debugging/electron/README.md

@@ -0,0 +1,65 @@
+## Electron - Main Process (desktop/main-app)
+
+To facilitate debugging, we set the reserved _Debug_ configuration with: `--enable-logging` and `--inspect=5859`
+
+* `--enable-logging`: This option will be passed to _Electron_, which will then print its own `debug` logs to the current console
+* `--inspect=5859`: If you prefer to use _Chrome DevTools_ for debugging, then you can listen to this port at `chrome://inspect` for debugging
+
+### WebStorm
+
+We've set up the _Debug Main_ Configurations in _WebStorm_ for you, and you can use it directly to do the _Debug_
+
+> Note that you should select the `Debug` button, not the `Run` button, as shown in the image below:
+
+> ![webstorm-debug-button](assets/webstorm-debug-button.png)
+
+### vscode
+
+We also set aside configured _Debug Main_ configurations for _vscode_, which you can do in the _Debug_ sidebar of _vscode_.
+
+As shown in the picture:
+
+![vscode-debug-button](assets/vscode-debug-button.png)
+
+### Additional Notes
+
+### `--enable-logging` param
+
+The version of `Electron` we are currently using does not support setting the output location of logs, as this feature was not supported until `Electron v14.0.0`, for which see: [electron/electron#25089](https://github.com/electron/electron/pull/25089)
+
+In the future, when _Flat_ upgrades `Electron` to _14.0.0_ or higher, we will support
+
+### `--inspect=5859` param
+
+If you want to use `Chrome DevTools` for debugging, you can refer to the following procedure:
+
+First you have to make sure you have started _Debug_ and also set a breakpoint before starting it.
+
+When _Debug_ starts, _Node.js_ will listen to port `5859`. In this case, open: `chrome://inspect` in the `Chrome` address bar, like this
+
+![chrome-inspect-page](assets/chrome-inspect-page.png)
+
+Click: _Open dedicated DevTools for Node_, a `DevTools` window will appear
+
+![chrome-inspect-node-devtools](assets/chrome-inspect-node-devtools.png)
+
+Your page may not match mine at this point, please don't worry. Click _Add connection_, enter: `localhost:5859` in the input box, then click _Add_ and you are ready to debug. It looks like the following:
+
+![chrome-inspect-node-devtools-launch](assets/chrome-inspect-node-devtools-launch.png)
+
+### `Watch` inconsistency issues
+
+We often need to use the `Watch` function during debugging, but it should be noted that what you _Watch_ The variable may not exist. Because the code executed by _Debug_ is compiled, it is possible that variable names will be overwritten.
+
+But the good news is that it has been found that such variable overrides only affect: `import` statements such as :
+
+* `import runtime from "./Runtime"` => `Runtime_1`
+* `import { app } from "electron""` => `electron_1`
+
+A screenshot can describe the problem more clearly:
+
+![watch-var](assets/watch-var.png)
+
+This problem is caused by the compilation of `tsc`', at present, there is no better way to solve it. We can only pay attention to it during operation.
+
+> This is true even if you use `ts-node` as a runtime. Because `ts-node` is essentially a dynamic way to do `tsc` as well.