improve dev docs

docs/docs/dev-env/dev_by_gitpod.md → docs/docs/dev-env/dev_by_online.md

@@ -1,24 +1,24 @@
 ---
-title: 使用 GitPod 开发 MiniOB
+title: 使用在线开发环境开发 MiniOB
 ---
 
-# 使用 GitPod 开发 MiniOB
+# 使用在线开发环境开发 MiniOB
 
-> [MiniOB](https://github.com/oceanbase/miniob) 是 [OceanBase](https://github.com/oceanbase/oceanbase) 联合华中科技大学推出的一款用于教学的小型数据库系统，希望能够帮助数据库爱好者系统性的学习数据库原理与实战。
+本篇文章介绍如何使用 [GitPod](https://www.gitpod.io/) 或 [GitHub Codespaces](https://github.com/features/codespaces)开发 [MiniOB](https://github.com/oceanbase/miniob)。对于代码开发调试，可以参考[使用 vscode 开发 miniob](./how_to_dev_miniob_by_vscode.md), [MiniOB 调试](./miniob-how-to-debug.md) 。
 
-本篇文章介绍如何使用 [GitPod](https://www.gitpod.io/) 开发 [MiniOB](https://github.com/oceanbase/miniob)。
-也可以参考这篇文章了解如何使用 Visual Studio Code 来开发调试 MiniOB。
-
-## GitPod 简介
+## GitPod 开发环境
+### GitPod 简介
 [GitPod](https://www.gitpod.io/) 是一个能让我们在任何地方都能方便开发自己代码的云平台。在开发时，GitPod会提供一个虚拟机一样的开发环境，开发平台是Linux，并且GitPod可以直接打开GitHub项目，支持很多IDE，比如Visual Studio Code、Clion、VIM等。
 
 ![GitPod支持的IDE](images/dev_by_gitpod_ides.png)
 
 本篇文章将介绍如何在GitPod上使用Visual Studio Code（浏览器版）来开发MiniOB。
 
-## 在 GitPod 上开发自己的 MiniOB
+注意: GitPod 可能需要[手机号验证](https://github.com/gitpod-io/gitpod/issues/11339)，如果无法通过验证，可以尝试其他开发环境。
+
+### 在 GitPod 上开发自己的 MiniOB
 
-### 创建自己的GitHub项目
+#### 创建自己的GitHub项目
 
 在开发MiniOB之前，应该先在GitHub上将MiniOB放在自己的私有仓库中。为了方便演示，我这里直接使用fork的方式，在自己的个人仓库中创建一个共有(public)仓库。
 
@@ -29,7 +29,7 @@ title: 使用 GitPod 开发 MiniOB
   ![Fork MiniOB 仓库](images/dev_by_gitpod_fork_repo.png)
 
 
-### 在 GitPod 上打开自己的项目
+#### 在 GitPod 上打开自己的项目
 
 使用 [GitPod](https://www.gitpod.io/) 打开自己的项目
 
@@ -54,7 +54,7 @@ title: 使用 GitPod 开发 MiniOB
 
 ![GitPod Workspaces](images/dev_by_gitpod_workspace.png)
 
-### 代码构建
+#### 代码构建
 
 **环境初始化**
 因为MiniOB当前已经将.vscode文件加入到项目中，所以可以直接使用当前已有的一些命令(task)来构建代码。
@@ -93,7 +93,7 @@ title: 使用 GitPod 开发 MiniOB
 
 miniob 虽然是cmake功能，可以使用vscode带的cmake配置，但是miniob在编译时，会使用一些变量来控制编译什么版本，比如是否编译UNITTEST，是否开启ASAN等。因此这里使用build.sh脚本来简化项目的编译命令。
 
-### 代码调试
+#### 代码调试
 与代码构建类似，MiniOB 可以支持在vscode中直接启动调试程序。启动的调试程序为默认构建项目，当前是 debug 模式编译的miniob。
 与普通的调试类似，可以自行设置断点。断点可以在运行程序之前也可以在其后。
 启动调试服务端后，打开一个新的终端，来运行客户端，以便向服务端发起命令。
@@ -125,7 +125,7 @@ vscode 为调试进程也创建了一个终端，可以在这里看到observer
 ![debug debugging view](images/dev_by_gitpod_debug_debugging_view.png)
 
 
-### 代码提交
+#### 代码提交
 作为一个GitHub项目，一个功能或者BUG开发完成后，需要将代码推送到远程仓库。vscode已经集成了GitHub和git插件，可以方便的进行操作。
 
 完成一个功能，就提交一次。这里输入commit message后直接提交即可。
@@ -152,56 +152,23 @@ Git的其它操作链接在这里
 
 ![git auth1](images/dev_by_gitpod_git_auth1.png)
 
-## 信息介绍
-
-### MiniOB 中的 tasks
-
-vscode 可以非常方便的运行任务(task)来运行预配置的命令，比如shell。
-miniob 的编译也可以通过脚本来执行(build.sh)。这里预配置了几个编译任务，可以按需自取，也可以按照需要，增加新的配置，运行自己的参数。
-
-下面是一个 debug 模式编译的示例，也是vscode工程默认的Build配置。这里做个简单介绍，以方便大家有需要的时候，修改配置满足自己需要。
-其中 
-- `label` 是一个任务名字，在 `Run task`的时候，可以看到
-- `type` 表示任务的类型。这里是一个shell脚本
-- `command` 这里是一个shell脚本的话，那command就是运行的命令，跟我们在终端上执行是一样的效果
-- `problemMatcher` 告诉vscode如何定位问题。这里不用设置，vscode可以自动检测
-- `group` 使用vscode将此任务设置为默认Build任务时，vscode自己设置上来的，不需要调整。
-
-```json
-{
-    "label": "build_debug",
-    "type": "shell",
-    "command": "bash build.sh debug",
-    "problemMatcher": [],
-    "group": {
-        "kind": "build",
-        "isDefault": true
-    }
-}
-```
-
-### MiniOB 中的 launch
-
-很多同学不习惯使用gdb的终端界面来调试程序，那么在 vscode 中调试miniob非常方便，与Visual Studio、Clion中类似，都有一个操作界面。
-vscode中启动调试程序是通过launch.json来配置的，这里简单介绍一下主要内容。
-
-下面是截取的一段关键内容。这里介绍一些关键字段
-- `type` 当前调试使用哪种类型。这里是lldb (我个人习惯了gdb，但是我没有找到，也不想找了)
-- `name` 这里会显示在vscode调试窗口启动时的名字中
-- `program` 要调试的程序。对miniob来说，我们通常都是调试服务端代码，这里就是observer的路径。workspaceFolder 是当前工程的路径，defaultBuildTask 是默认构建的任务名称，与我们的构建路径刚好一致。observer 是编译完成安装在构建路径的bin下。
-- `args` 启动程序时的命令行参数。在终端上，大家也可以这么启动observer: `./bin/observer -f ../etc/observer.ini -s miniob.sock
-- `cwd` observer 运行时的工作目录，就是在observer程序中获取当前路径时，就会是这个路径。
-
-```json
-{
-    "type": "lldb",
-    "request": "launch",
-    "name": "Debug",
-    "program": "${workspaceFolder}/${defaultBuildTask}/bin/observer",
-    "args": ["-f", "${workspaceFolder}/etc/observer.ini", "-s", "miniob.sock"],
-    "cwd": "${workspaceFolder}/${defaultBuildTask}/"
-}
-```
-
-注意，如果要调试 release 或者其它任务编译出来的observer，就需要调整这个文件，或者新增一个配置，因为这个配置文件指定的observer路径是默认的build。
+## GitHub Codespaces 开发环境
+GitHub Codespaces 是托管在云中的开发环境。它允许开发⼈员通过浏览器或从本地的 Visual Studio Code IDE 直接进⾏调试 GitHub 上的代码。GitHub Codespaces 的使用十分方便，但是实际使用体验受限于网络环境，适合网络环境比较好的开发者使用。
+
+### 在 GitHub Codespaces 上开发自己的 MiniOB
+
+#### 创建自己的GitHub项目
+
+在开发 MiniOB 之前，应该先在 GitHub 上将 MiniOB 放在自己的私有仓库中。具体方法可以参考: [创建 Github 私有仓库](../game/github-introduction.md#github-私有仓库创建)
+
+#### 在 GitHub Codespaces 上打开自己的项目
+
+在浏览器中打开自己的私有仓库，依次点击截图中的 `Code` -> `Codespaces` -> `Create codespace on main`，即可初始化一个 MiniOB 在线开发环境。
+
+![GitHub Codespaces](images/dev_by_github_codespaces.png)
+
+#### 代码调试
+在GitHub Codespaces 上开发调试 MiniOB 与本地环境基本类似，这里不再重复。可以参考：对于代码开发调试，可以参考[使用 vscode 开发 miniob](./how_to_dev_miniob_by_vscode.md), [MiniOB 调试](./miniob-how-to-debug.md) 。
+
+
 

docs/docs/dev-env/how_to_dev_in_docker_container_by_vscode_on_windows.md

@@ -41,6 +41,16 @@ title: 在windows上通过docker配置环境并利用vscode调试代码（手把
 docker run --privileged -d --name=miniobtest oceanbase/miniob
 ```
 
+注意：如果这里遇到网络问题（例如：timeout 相关提示），请尝试用其他镜像源拉取镜像。
+![docker pull timeout](images/docker_pull_timeout.png)
+```bash
+# 下面的命令三选一即可
+docker pull oceanbase/miniob         # pull from docker hub
+docker pull ghcr.io/oceanbase/miniob && docker tag ghcr.io/oceanbase/miniob oceanbase/miniob # pull from github
+docker pull quay.io/oceanbase/miniob && docker tag quay.io/oceanbase/miniob oceanbase/miniob # pull from github # pull from quay.io
+```
+
+
 其中 --name=miniobtest  这个“miniobtest”是自己容器的名字 可以自己改 
 这个代码大概理解成从远程oceanbase/miniob拉取适合miniob的配置好的环境
 

docs/docs/dev-env/introduction.md

@@ -4,12 +4,20 @@ title: 开发环境介绍
 
 # 搭建开发环境
 
-MiniOB 当前可以在Linux/MacOS上编译，所以开发环境最好是Linux或者MacOS。Windows上可以使用WSL2，或者使用Docker。这里有几个文档，大家可以参考并选择自己的开发环境。另外，很多同学喜欢使用visual studio code开发，MiniOB 中也将vscode的一些配置文件放在了仓库中，比如 .vscode/tasks.json 和 .vscode/launch.json，可以参考使用。
-
-- [使用 GitPod 开发 MiniOB](dev_by_gitpod.md)
-- [开发环境搭建(本地调试, 适用 Linux 和 Mac)](how_to_dev_miniob_by_vscode.md)
-- [开发环境搭建(远程调试, 适用于 Window, Linux 和 Mac)](how_to_dev_in_docker_container_by_vscode.md)
-- [Windows 使用Docker开发MiniOB](how_to_dev_miniob_by_docker_on_windows.md)
-- [手把手教你在windows上用docker和vscode配置环境](how_to_dev_in_docker_container_by_vscode_on_windows.md)
-- [使用Docker开发MiniOB](how-to-dev-using-docker.md)
-- [MiniOB 调试](miniob-how-to-debug.md)
+每个人的开发环境各不相同，这里介绍了 Linux/MacOS/Windows 三类操作系统上搭建 MiniOB 的开发环境，以及推荐使用的IDE（VSCode）的调试方法。
+首先，大家需要清楚 MiniOB 当前只能在 Linux/MacOS 操作系统上编译。因此，如果是使用 Windows 操作系统的同学，需要首先准备 Linux 的虚拟环境（例如，WSL2，Docker，虚拟机等）。
+下面提供了多种开发环境的搭建方法，请大家根据自己的实际情况选择合适的文档进行学习阅读。
+## 在线开发环境
+在线开发环境的优点是无需安装任何软件，开箱即用，几乎是一键初始化完成开发环境。但是在网络受限时，可能无法使用，或者体验比较差。如果希望使用在线开发环境的同学可以参考[使用在线开发环境开发 MiniOB](dev_by_online.md)。
+## Linux/MacOS 开发环境
+对于使用 Linux/MacOS 操作系统的同学，可以参考[使用 VSCode 开发 MiniOB](./how_to_dev_miniob_by_vscode.md)。
+## Windows 开发环境
+对于使用 Windows 操作系统的同学，需要先准备 Linux 的虚拟环境（例如，WSL2，Docker，虚拟机等），之后才能在 Linux 的虚拟环境上开发 MiniOB。
+
+使用 Docker 容器开发，可以参考[使用 Docker 开发 MiniOB](how-to-dev-using-docker.md)或[Windows 使用Docker开发MiniOB](how_to_dev_miniob_by_docker_on_windows.md)或热心同学的[手把手教你在windows上用docker和vscode配置环境](how_to_dev_in_docker_container_by_vscode_on_windows.md)。
+
+上述三篇文档的详细程度依次递增，可以根据实际情况选择阅读。
+## 远程开发环境
+对于有远程开发环境（例如云服务器等）的同学不受本地操作系统的限制，可以参考：[开发环境搭建(远程调试)](how_to_dev_in_docker_container_by_vscode.md)
+## 调试（Debug）介绍
+miniob 的调试（debug）方法可以参考[MiniOB 调试](miniob-how-to-debug.md)。

docs/docs/dev-env/miniob-how-to-debug.md

@@ -231,4 +231,55 @@ LOG_CONSOLE_LEVEL=1
 
 ### Visual Studio Code 调试
 代码中已经为vscode配置了launch.json，可以直接启动调试。
-launch.json中有两个调试配置，一个是Debug，一个是LLDB。其中Debug使用cppdbg，会自动探测调试工具gdb或lldb，而LLDB会使用lldb调试工具。通常情况下，大家使用Debug就可以了，但是我在测试过程中发现cppdbg不能在macos上正常工作，因而增加了LLDB的配置，以便在macos上调试，如果使用macos的同学，可以使用LLDB配置启动调试程序。
+launch.json中有两个调试配置，一个是Debug，一个是LLDB。其中Debug使用cppdbg，会自动探测调试工具gdb或lldb，而LLDB会使用lldb调试工具。通常情况下，大家使用Debug就可以了，但是我在测试过程中发现cppdbg不能在macos上正常工作，因而增加了LLDB的配置，以便在macos上调试，如果使用macos的同学，可以使用LLDB配置启动调试程序。
+
+#### MiniOB 中的 tasks
+
+vscode 可以非常方便的运行任务(task)来运行预配置的命令，比如shell。
+miniob 的编译也可以通过脚本来执行(build.sh)。这里预配置了几个编译任务，可以按需自取，也可以按照需要，增加新的配置，运行自己的参数。
+
+下面是一个 debug 模式编译的示例，也是vscode工程默认的Build配置。这里做个简单介绍，以方便大家有需要的时候，修改配置满足自己需要。
+其中 
+- `label` 是一个任务名字，在 `Run task`的时候，可以看到
+- `type` 表示任务的类型。这里是一个shell脚本
+- `command` 这里是一个shell脚本的话，那command就是运行的命令，跟我们在终端上执行是一样的效果
+- `problemMatcher` 告诉vscode如何定位问题。这里不用设置，vscode可以自动检测
+- `group` 使用vscode将此任务设置为默认Build任务时，vscode自己设置上来的，不需要调整。
+
+```json
+{
+    "label": "build_debug",
+    "type": "shell",
+    "command": "bash build.sh debug",
+    "problemMatcher": [],
+    "group": {
+        "kind": "build",
+        "isDefault": true
+    }
+}
+```
+
+#### MiniOB 中的 launch
+
+很多同学不习惯使用gdb的终端界面来调试程序，那么在 vscode 中调试miniob非常方便，与Visual Studio、Clion中类似，都有一个操作界面。
+vscode中启动调试程序是通过launch.json来配置的，这里简单介绍一下主要内容。
+
+下面是截取的一段关键内容。这里介绍一些关键字段
+- `type` 当前调试使用哪种类型。这里是lldb (我个人习惯了gdb，但是我没有找到，也不想找了)
+- `name` 这里会显示在vscode调试窗口启动时的名字中
+- `program` 要调试的程序。对miniob来说，我们通常都是调试服务端代码，这里就是observer的路径。workspaceFolder 是当前工程的路径，defaultBuildTask 是默认构建的任务名称，与我们的构建路径刚好一致。observer 是编译完成安装在构建路径的bin下。
+- `args` 启动程序时的命令行参数。在终端上，大家也可以这么启动observer: `./bin/observer -f ../etc/observer.ini -s miniob.sock
+- `cwd` observer 运行时的工作目录，就是在observer程序中获取当前路径时，就会是这个路径。
+
+```json
+{
+    "type": "lldb",
+    "request": "launch",
+    "name": "Debug",
+    "program": "${workspaceFolder}/${defaultBuildTask}/bin/observer",
+    "args": ["-f", "${workspaceFolder}/etc/observer.ini", "-s", "miniob.sock"],
+    "cwd": "${workspaceFolder}/${defaultBuildTask}/"
+}
+```
+
+注意，如果要调试 release 或者其它任务编译出来的observer，就需要调整这个文件，或者新增一个配置，因为这个配置文件指定的observer路径是默认的build。

docs/docs/game/debug-output.md

@@ -41,4 +41,12 @@ miniob > select * from t;
 id
 1
 
+```
+
+在训练营中，需要手动修改 `session.h` 文件中的代码来开启调试/关闭调试。
+```c++
+// 将 Session::sql_debug_ 设置为 false，关闭调试
+bool sql_debug_ = false;
+// 将 Session::sql_debug_ 设置为 true，开启调试
+bool sql_debug_ = true;
 ```