diff --git a/docs/docs/dev-env/dev_by_gitpod.md b/docs/docs/dev-env/dev_by_online.md similarity index 63% rename from docs/docs/dev-env/dev_by_gitpod.md rename to docs/docs/dev-env/dev_by_online.md index 37299c1db..a66874e60 100644 --- a/docs/docs/dev-env/dev_by_gitpod.md +++ b/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) 。 + + diff --git a/docs/docs/dev-env/how_to_dev_in_docker_container_by_vscode_on_windows.md b/docs/docs/dev-env/how_to_dev_in_docker_container_by_vscode_on_windows.md index e206ffb46..2b1bb9811 100644 --- a/docs/docs/dev-env/how_to_dev_in_docker_container_by_vscode_on_windows.md +++ b/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的配置好的环境 diff --git a/docs/docs/dev-env/images/dev_by_github_codespaces.png b/docs/docs/dev-env/images/dev_by_github_codespaces.png new file mode 100644 index 000000000..baa4550e0 Binary files /dev/null and b/docs/docs/dev-env/images/dev_by_github_codespaces.png differ diff --git a/docs/docs/dev-env/images/docker_pull_timeout.png b/docs/docs/dev-env/images/docker_pull_timeout.png new file mode 100644 index 000000000..cacca7056 Binary files /dev/null and b/docs/docs/dev-env/images/docker_pull_timeout.png differ diff --git a/docs/docs/dev-env/introduction.md b/docs/docs/dev-env/introduction.md index 0633594fd..1cf14f9da 100644 --- a/docs/docs/dev-env/introduction.md +++ b/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)。 diff --git a/docs/docs/dev-env/miniob-how-to-debug.md b/docs/docs/dev-env/miniob-how-to-debug.md index 75315bf20..2e5a3a774 100644 --- a/docs/docs/dev-env/miniob-how-to-debug.md +++ b/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配置启动调试程序。 \ No newline at end of file +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。 diff --git a/docs/docs/game/debug-output.md b/docs/docs/game/debug-output.md index 7f9b5df4b..4c35726d1 100644 --- a/docs/docs/game/debug-output.md +++ b/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; ``` \ No newline at end of file