From 1f2588a957416d78e109b6588be0101f421b9078 Mon Sep 17 00:00:00 2001 From: SPeak Date: Sun, 26 May 2024 04:22:20 +0800 Subject: [PATCH] update readme (#18) update readme --- README.md | 196 +++++++++----------------------------------- book/src/SUMMARY.md | 1 + book/src/dslings.md | 194 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 236 insertions(+), 155 deletions(-) create mode 100644 book/src/dslings.md diff --git a/README.md b/README.md index 01d9d39..21c7d7e 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,22 @@ # 动手写数据结构 | d2ds - WIP -d2ds(Dive into Data Structures) - 强调**动手实践**的**数据结构练习代码和书籍** +d2ds(Dive into Data Structures) - 强调**动手实践**的**数据结构**学习项目，其中包含**在线书籍、公开课、练习代码**等子项目 -**推荐使用方式:** [d2ds-book](https://sunrisepeak.github.io/d2ds/) -> [d2ds-video](https://www.bilibili.com/video/BV1hD421T7sU) -> [d2ds-dslings](https://github.com/Sunrisepeak/d2ds/tree/main/exercises) -> [contributor]() +| [项目主页](https://sunrisepeak.github.io/d2ds-courses) | +| ------------------------------------------------------------ | +| [d2ds-book](https://sunrisepeak.github.io/d2ds) - [d2ds-courses](https://sunrisepeak.github.io/d2ds-courses) - [d2ds-dslings](dslings) - [dstruct](https://github.com/Sunrisepeak/dstruct) | +--- -## d2ds-book | 书籍/材料 +## book & courses | 阅读 -[在线阅读](https://sunrisepeak.github.io/d2ds/) +| d2ds | 材料 | 视频 | 参考 | 备注 | +| --- | --- | --- | --- | --- | +| Array | [chapter1](http://127.0.0.1:3000/chapter_01_array.html) | [video1](https://www.bilibili.com/video/BV1hD421T7sU) - [video2](https://www.bilibili.com/video/BV16t421w7c2) | [dstruct::Array](https://github.com/Sunrisepeak/dstruct/blob/main/core/ds/array/Array.hpp) | [备用地址](https://zhuanlan.zhihu.com/p/693936490) | +| Vector | [chapter2](http://127.0.0.1:3000/chapter_01_array.html) | [video1](https://www.bilibili.com/video/BV1K1421z7kt) - [video2](https://www.bilibili.com/video/BV1yb421B7ZG) | [dstruct::Vector](https://github.com/Sunrisepeak/dstruct/blob/main/core/ds/array/Vector.hpp) | [备用地址](https://zhuanlan.zhihu.com/p/696455403) | +| SinglyLink | [chapter3](http://127.0.0.1:3000/chapter_04_embeddedlist.html) | [video1](https://www.bilibili.com/video/BV1ND421V7Wn) - [video2](https://www.bilibili.com/video/BV1ir421w71C) | [dstruct::SinglyLink](https://github.com/Sunrisepeak/dstruct/blob/main/core/ds/linked-list/EmbeddedList.hpp#L15) | [备用地址](https://zhuanlan.zhihu.com/p/699299313) | -## d2ds-dslings | 代码练习 +## d2ds-dslings | 练习 通过使用dslings自动化检测的**编译器驱动开发模式**来进行代码练习 @@ -19,7 +26,7 @@ d2ds(Dive into Data Structures) - 强调**动手实践**的**数据结构练习 git clone --recursive git@github.com:Sunrisepeak/d2ds.git ``` -### 安装xmake +### 配置环境 **linux/macos** @@ -37,172 +44,51 @@ bash tools/install.unix.sh tools\install.win.bat ``` -### dslings使用流程 - -#### 第一步: 开启代码检测 +### 执行dslings进入练习 -在本地[d2ds仓库](https://github.com/Sunrisepeak/d2ds)的根目录执行如下命令 +> 更多详情见[dslings使用指南](book/src/dslings.md) ```bash xmake dslings ``` -程序开始自动的测试/校验, 直到一个没有完成(或检测不通过)的练习代码。dslings会在控制台输出提示信息。如: - -- 练习进度 -- 练习的代码路径信息 -- 编译期错误信息提示 -- 运行时错误提示 - -> **注** -> -> - 执行命令前, 请确保电脑已经配置了C++环境, 并安装了[xmake](https://github.com/xmake-io/xmake)构建工具 -> -> - 建议使用vscode作为代码练习的编辑器, 用**ctrl+鼠标左键**点击路径就可以自动转跳到目标位置 -> -> - 由于vscode的C/C++插件会检测文件变化, 可以参考[issue-5](https://github.com/Sunrisepeak/d2ds/issues/5)来避免卡顿 - -#### 第二步: 根据dslings提示, 找到对应的练习代码 - -```bash -🌏Progress: [>-----------------------------] 0/29 +## 社区 | 交流 -[Target: 0.dslings-0] - -❌ Error: Compilation/Running failed for tests/dslings.0.cpp: - - The code exist some error! - -Output: -==================== -[ 50%]: cache compiling.release tests/dslings.0.cpp -error: tests/dslings.0.cpp:20:11: error: ‘MaxValue’ is not a member of ‘d2ds’ - 20 | d2ds::MaxValue mVal(2); - | ^~~~~~~~ -In file included from tests/dslings.0.cpp:14: -tests/dslings.0.cpp:22:20: error: ‘mVal’ was not declared in this scope - 22 | d2ds_assert_eq(mVal.get(), 2); - | ^~~~ -./common/common.hpp:28:9: note: in definition of macro ‘d2ds_assert_eq’ - 28 | if (a != b) {\ - | ^ - > in tests/dslings.0.cpp - - -==================== - -Homepage: https://github.com/Sunrisepeak/d2ds-courses -``` +### ShowYourCode-2024 -执行命令后dslings程序会停在最近的未完成的练习, 并会"实时"检测和这个练习相关的数据结构代码的实现。我们可以根据dslings在控制台的输出找到对应的练习代码: +> 代码分享、交流、解读 -```cpp -// dslings.0.cpp - readonly -// -// 描述: -// 通过实现一个MaxVal类型(保存最大值), 来介绍dslings的"编译器驱动开发" -// 即根据编译器的错误提示来完成这个训练流程的演示Demo, 并且通常为了降低难度会把一个'数据结构'的实现分成多个检测模块. -// 如: dslings.0.cpp dslings.1.cpp dslings.2.cpp -// -// 目标/要求: -// - 不修改该代码检测文件 -// - 在exercises/dslings.hpp中完成你的代码设计 -// - 通过所有编译器检测 和 断言 -// +| id | 练习代码 | 视频解读 | 文章解读 | 交流 | +| --- | --- | --- | --- | --- | +| [Sunrisepeak](https://github.com/Sunrisepeak) | [d2ds-sunrisepeak](https://github.com/UnknownBugs/d2ds-sunrisepeak) | | | [discussion-pages](https://github.com/Sunrisepeak/d2ds/discussions/19) | -#include "common/common.hpp" +**创建讨论页** -#include "exercises/dslings.hpp" +在[d2ds论坛](https://github.com/Sunrisepeak/d2ds/discussions)创建一个你的ShowYourCode讨论/交流页主版(用于后续表格中) - 格式见[ShowYourCode-2024 | Sunrisepeak 交流讨论页](https://github.com/Sunrisepeak/d2ds/discussions/19) -int main() { +**向本仓库发起PR** - d2ds::MaxValue mVal(2); +填写自己的相关链接到上述表格中, 并向本仓库发起PR - d2ds_assert_eq(mVal.get(), 2); +**表格介绍** - HONLY_LOGI_P("Hello D2DS!"); - - D2DS_WAIT - - return 0; -} -``` - -#### 第三步: 阅读练习描述和要求并完成练习 - -根据对应的练习代码中给的描述和要求完成该练习, 过程中可以结合dslings在控制台的提示来进行相关数据结构练习的代码设计。当正确完成代码后, dslings就会更新控制的输出给出对应的提示 - -```bash -🌏Progress: [>-----------------------------] 0/29 - -[Target: 0.dslings-0] - -✅ Successfully ran tests/dslings.0.cpp! - -🎉 The code is compiling! 🎉 - -Output: -==================== -[D2DS LOGI]: - ✅ | mVal.get() == 2 (2 == 2) -[D2DS LOGI]: - Hello D2DS! -[D2DS LOGW]: main: tests/dslings.0.cpp:26 - 🥳 Delete the D2DS_WAIT to continue... - -==================== - -Homepage: https://github.com/Sunrisepeak/d2ds-courses -``` +- **练习代码:** 包含自己练习代码实现的d2ds的fork仓库 +- **视频解读:** 对自己的代码实现的解读、做练习的过程等其他d2ds相关的代码分析 +- **文章解读:** 相关的代码分析的文章(如上视频解读) -#### 第四步: 注释D2DS_WAIT, 进入下一个练习 - -根据dslings在控制台的提示信息, 找到`tests/dslings.0.cpp:26`, 并进行注释或者删除。 -dslings就会进入下一个练习并进行检测 - -```bash -int main() { - - d2ds::MaxValue mVal(2); - - d2ds_assert_eq(mVal.get(), 2); - - HONLY_LOGI_P("Hello D2DS!"); - - //D2DS_WAIT - - return 0; -} -``` - -## 其他工具 - -### xmake dslings - -从指定练习开始检测, 支持模糊匹配 - -```bash -xmake dslings -s [target] -#xmake dslings -s vector -``` - -### xmake d2ds - -查看版本信息 - -```bash -xmake d2ds info -``` - -查看工具使用 +> 注: +> +> - 关于链接: 视频/文章解读, 最好是视频合集/专栏的链接, 或者是一个目录页链接 +> - 费曼学习法: 学习练习之后, 尝试把自己学到的内容进行分享给他人, 在尽力让其他人听懂的过程中, 促使自己更加深入的理解 -```bash -xmake d2ds help -``` +### 交流渠道 -同步(主仓库)最新代码 +- **即时交流(QQ群):** 167535744 +- **论坛:** [github-discussions](https://github.com/Sunrisepeak/d2ds-courses/discussions) +- **问题交流&反馈:** [github-issues](https://github.com/Sunrisepeak/d2ds-courses/issues) -```bash -xmake d2ds update -``` - ---- +## 贡献方式 | 贡献 -[项目主页](https://sunrisepeak.github.io/d2ds-courses/) | [ShowYourCode](https://github.com/Sunrisepeak/d2ds-courses/tree/main/show-your-code) | [dstruct开源库](https://github.com/Sunrisepeak/DStruct) \ No newline at end of file +- **参与社区交流:** 反馈问题、参与社区问题讨论 +- **参与项目开发:** 修复Bug、开发&优化新功能/模块 +- **参与项目的宣传和推广:** 让更多的人能参与到项目的学习和建设当中, 以至于帮助到更多同学 \ No newline at end of file diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 8f280d2..9318a17 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -3,6 +3,7 @@ # 阅读准备 - [导读](./Instroduction.md) - [资源](./Resources.md) +- [环境配置](./dslings.md) # 常用数据结构 - [数组](0_array.md) diff --git a/book/src/dslings.md b/book/src/dslings.md new file mode 100644 index 0000000..40045fe --- /dev/null +++ b/book/src/dslings.md @@ -0,0 +1,194 @@ +# d2ds-dslings | 代码练习 + +通过使用dslings自动化检测的**编译器驱动开发模式**来进行代码练习 + +## 代码下载 + +```bash +git clone --recursive git@github.com:Sunrisepeak/d2ds.git +``` + +## 安装xmake + +**linux/macos** + +> 使用bash执行tools目录下的安装脚本 + +```bash +bash tools/install.unix.sh +``` + +**windows** + +> 执行tools目录下的安装脚本 或 直接双击运行 + +```bash +tools\install.win.bat +``` + +## dslings使用流程 + +### 第一步: 开启代码检测 + +在本地[d2ds仓库](https://github.com/Sunrisepeak/d2ds)的根目录执行如下命令 + +```bash +xmake dslings +``` + +程序开始自动的测试/校验, 直到一个没有完成(或检测不通过)的练习代码。dslings会在控制台输出提示信息。如: + +- 练习进度 +- 练习的代码路径信息 +- 编译期错误信息提示 +- 运行时错误提示 + +> **注** +> +> - 执行命令前, 请确保电脑已经配置了C++环境, 并安装了[xmake](https://github.com/xmake-io/xmake)构建工具 +> +> - 建议使用vscode作为代码练习的编辑器, 用**ctrl+鼠标左键**点击路径就可以自动转跳到目标位置 +> +> - 由于vscode的C/C++插件会检测文件变化, 可以参考[issue-5](https://github.com/Sunrisepeak/d2ds/issues/5)来避免卡顿 + +### 第二步: 根据dslings提示, 找到对应的练习代码 + +```bash +🌏Progress: [>-----------------------------] 0/29 + +[Target: 0.dslings-0] + +❌ Error: Compilation/Running failed for tests/dslings.0.cpp: + + The code exist some error! + +Output: +==================== +[ 50%]: cache compiling.release tests/dslings.0.cpp +error: tests/dslings.0.cpp:20:11: error: ‘MaxValue’ is not a member of ‘d2ds’ + 20 | d2ds::MaxValue mVal(2); + | ^~~~~~~~ +In file included from tests/dslings.0.cpp:14: +tests/dslings.0.cpp:22:20: error: ‘mVal’ was not declared in this scope + 22 | d2ds_assert_eq(mVal.get(), 2); + | ^~~~ +./common/common.hpp:28:9: note: in definition of macro ‘d2ds_assert_eq’ + 28 | if (a != b) {\ + | ^ + > in tests/dslings.0.cpp + + +==================== + +Homepage: https://github.com/Sunrisepeak/d2ds-courses +``` + +执行命令后dslings程序会停在最近的未完成的练习, 并会"实时"检测和这个练习相关的数据结构代码的实现。我们可以根据dslings在控制台的输出找到对应的练习代码: + +```cpp +// dslings.0.cpp - readonly +// +// 描述: +// 通过实现一个MaxVal类型(保存最大值), 来介绍dslings的"编译器驱动开发" +// 即根据编译器的错误提示来完成这个训练流程的演示Demo, 并且通常为了降低难度会把一个'数据结构'的实现分成多个检测模块. +// 如: dslings.0.cpp dslings.1.cpp dslings.2.cpp +// +// 目标/要求: +// - 不修改该代码检测文件 +// - 在exercises/dslings.hpp中完成你的代码设计 +// - 通过所有编译器检测 和 断言 +// + +#include "common/common.hpp" + +#include "exercises/dslings.hpp" + +int main() { + + d2ds::MaxValue mVal(2); + + d2ds_assert_eq(mVal.get(), 2); + + HONLY_LOGI_P("Hello D2DS!"); + + D2DS_WAIT + + return 0; +} +``` + +### 第三步: 阅读练习描述和要求并完成练习 + +根据对应的练习代码中给的描述和要求完成该练习, 过程中可以结合dslings在控制台的提示来进行相关数据结构练习的代码设计。当正确完成代码后, dslings就会更新控制的输出给出对应的提示 + +```bash +🌏Progress: [>-----------------------------] 0/29 + +[Target: 0.dslings-0] + +✅ Successfully ran tests/dslings.0.cpp! + +🎉 The code is compiling! 🎉 + +Output: +==================== +[D2DS LOGI]: - ✅ | mVal.get() == 2 (2 == 2) +[D2DS LOGI]: - Hello D2DS! +[D2DS LOGW]: main: tests/dslings.0.cpp:26 - 🥳 Delete the D2DS_WAIT to continue... + +==================== + +Homepage: https://github.com/Sunrisepeak/d2ds-courses +``` + +### 第四步: 注释D2DS_WAIT, 进入下一个练习 + +根据dslings在控制台的提示信息, 找到`tests/dslings.0.cpp:26`, 并进行注释或者删除。 +dslings就会进入下一个练习并进行检测 + +```bash +int main() { + + d2ds::MaxValue mVal(2); + + d2ds_assert_eq(mVal.get(), 2); + + HONLY_LOGI_P("Hello D2DS!"); + + //D2DS_WAIT + + return 0; +} +``` + +## 工具 | 快捷命令 + +### xmake dslings + +从指定练习开始检测, 支持模糊匹配 + +```bash +# xmake dslings 默认从第一开始检测 +xmake dslings -s [target] +#xmake dslings -s vector +``` + +### xmake d2ds + +查看版本信息 + +```bash +xmake d2ds info +``` + +查看工具使用 + +```bash +xmake d2ds help +``` + +同步(主仓库)最新代码 + +```bash +xmake d2ds update +``` \ No newline at end of file