拆分检验配置的方法从而便于拓展和阅读

- 修复检验配置过程中的不一致问题 - 隐含调试 CMake 的提示
FeignClaims · Mar 22, 2024 · 4e18e6f · 4e18e6f
1 parent 6cae501
commit 4e18e6f
Show file tree

Hide file tree

Showing 17 changed files with 177 additions and 94 deletions.
diff --git a/add_your_program/main.rst b/add_your_program/main.rst
@@ -0,0 +1,10 @@
+************************************************************************************************************************
+4.添加你自己的程序
+************************************************************************************************************************
+
+你只需要在 ``CMakeLists.txt`` 中用 ``add_code(程序名 源文件1 源文件2...)`` 添加即可, 具体参考 ``请读我`` 文件.
+
+在 ``src`` 文件夹中我给了两个程序示例, 请对照 ``CMakeLists.txt`` 中是怎么添加它们的:
+
+- ``example_single``: 单个源文件组成的程序.
+- ``example_multiple``: 多个源文件组成的程序.
diff --git a/appendix/explain.rst b/appendix/explain.rst
@@ -143,10 +143,22 @@ symlink_compile_commands.cmake
 tasks.json
 ------------------------------------------------------------------------------------------------------------------------
 
-该文件夹下能使用的任务, 如编译源文件等.
+该文件夹下能使用的任务, 如编译源文件等, 目前配置有:
+
+:menuselection:`Clang-Tidy: fix current file`
+  使用 clang-tidy 修复当前文件.
 
 ------------------------------------------------------------------------------------------------------------------------
 launch.json
 ------------------------------------------------------------------------------------------------------------------------
 
-该文件夹下能使用调试任务, 用于调试.
+该文件夹下能使用调试任务, 用于调试, 目前配置有:
+
+:menuselection:`LLDB: debug the active target`
+  使用 LLDB 软件对 CMake *当前预运行的目标* 进行调试, 在此即对选择的 C++ 程序进行调试.
+
+:menuselection:`CMake: debug configuration`
+  对 CMake 的配置即 ``CMakeLists.txt`` 进行调试.
+
+:menuselection:`CMake: clean and debug configuration`
+  清理之前的 CMake 配置缓存, 并对 CMake 的配置即 ``CMakeLists.txt`` 进行调试.
diff --git a/appendix/learning.rst b/appendix/learning.rst
@@ -4,7 +4,7 @@ C++ 和 CMake 的学习建议
 
 本教程虽然使用 CMake 创建了一个学习用文件夹, 但只是为了提供一个配置好的开发/学习环境, 并不适合复杂的项目.
 
-如果需要配置项目, 请自行学习 CMake (可参考 :ref:`我的学习建议 <question_board:学习大纲_CMake>`), 并修改根目录下的 ``CMakeLists.txt``.
+如果需要配置项目, 请自行学习 CMake (可参考 :ref:`我的学习建议 <question_board:学习大纲_CMake>`) 和了解 VSCode 的 `CMake Tools 插件 <https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/README.md>`_, 并修改根目录下的 ``CMakeLists.txt``.
 
 此外, 建议参考 :doc:`/appendix/bibliography` 给出的文档自行修改配置.
 

diff --git a/index.rst b/index.rst
@@ -28,7 +28,8 @@ Windows/MacOS/Linux 上 VSCode 配置 C++: Clang + Clang-based Tools + CMake + C
   download_and_install_macos/index.rst
   download_and_install_linux/index.rst
   configure/main.rst
-  verify/main.rst
+  verify/index.rst
+  add_your_program/main.rst
   third_party/index.rst
   ohmyzsh/main.rst
   visual_studio/main.rst

diff --git a/verify/cmake侧边栏.png b/verify/cmake侧边栏.png
diff --git a/verify/cmake工具列表.png b/verify/cmake工具列表.png
diff --git a/verify/cmake选择运行目标.png b/verify/cmake选择运行目标.png
diff --git a/verify/debug/main.rst b/verify/debug/main.rst
@@ -0,0 +1,43 @@
+************************************************************************************************************************
+调试程序
+************************************************************************************************************************
+
+========================================================================================================================
+选择运行任务
+========================================================================================================================
+
+VSCode 只是通用的编辑器, 并不知道你会如何进行调试或运行, 所以需要在 ``.vscode/launch.json`` 中手动配置运行任务. 教程中已经对此进行配置, 以下展示如何使用.
+
+从左侧侧边栏切换到 :menuselection:`运行和调试`, 点击上方 :menuselection:`▶播放按钮` 右侧下拉框, 则如图所示:
+
+.. figure:: 调试和运行侧边栏.png
+
+图中展示了三个我已配置好的运行任务, 你可以点击 :menuselection:`▶播放按钮` 或按快捷键 :KBD:`F5` 运行选择的任务:
+
+:menuselection:`LLDB: debug the active target`
+  使用 LLDB 软件对 CMake *当前预运行的目标* 进行调试, 在此即对选择的 C++ 程序进行调试.
+
+:menuselection:`CMake: debug configuration`
+  对 CMake 的配置即 ``CMakeLists.txt`` 进行调试.
+
+:menuselection:`CMake: clean and debug configuration`
+  清理之前的 CMake 配置缓存, 并对 CMake 的配置即 ``CMakeLists.txt`` 进行调试.
+
+========================================================================================================================
+调试 test
+========================================================================================================================
+
+根据上面的描述, 要调试 test, 我们将 *当前预生成的目标* 和 *当前预运行的目标* 均设置为 :menuselection:`[test]`, 点击 :menuselection:`运行和调试 --> ▶播放按钮` 或按快捷键 :KBD:`F5` 即可.
+
+当然, 在调试前, 我们需要在 test 程序对应的源文件 :cpp:`test/main.cpp` 中设置断点:
+
+1. 点开 ``test/main.cpp``.
+2. 选择要中断的行, 通过 :KBD:`左击` 行号左边空白区域设置断点, 例如设置在第 7 行 :cpp:`int x{};` 处.
+
+.. figure:: 设置断点.png
+
+  设置断点
+
+.. hint::
+
+  更多调试相关内容见于 :ref:`断点调试的使用 <question_board:debugger>`.
diff --git a/verify/debug/设置断点.png b/verify/debug/设置断点.png
diff --git a/verify/debug/调试和运行侧边栏.png b/verify/debug/调试和运行侧边栏.png
diff --git a/verify/diagnostics/main.rst b/verify/diagnostics/main.rst
@@ -0,0 +1,12 @@
+************************************************************************************************************************
+观察诊断信息
+************************************************************************************************************************
+
+观察 ``int main()`` 函数内的 ``int x{};``, ``x`` 下方应有黄线.
+
+- 黄色的信息为警告, 表示代码写得可能不够好, 如何处理见于 :doc:`/appendix/about_warnings/main`.
+- 红色的信息为错误, 表示代码无法运行.
+
+.. figure:: 诊断信息示例.png
+
+  诊断信息
diff --git a/verify/诊断信息示例.png → verify/diagnostics/诊断信息示例.png b/verify/诊断信息示例.png → verify/diagnostics/诊断信息示例.png
diff --git a/verify/index.rst b/verify/index.rst
@@ -0,0 +1,13 @@
+************************************************************************************************************************
+3.检验配置结果和实际使用
+************************************************************************************************************************
+
+打开 ``test/main.cpp``, 以下操作均在 ``test/main.cpp`` 中进行.
+
+.. toctree::
+  :maxdepth: 1
+  :caption: 目录
+
+  diagnostics/main.rst
+  run/main.rst
+  debug/main.rst
diff --git a/verify/main.rst b/verify/main.rst
diff --git a/verify/run/cmake工具列表.png b/verify/run/cmake工具列表.png
diff --git a/verify/cmake选择生成目标.png → verify/run/cmake选择生成目标.png b/verify/cmake选择生成目标.png → verify/run/cmake选择生成目标.png
diff --git a/verify/run/main.rst b/verify/run/main.rst
@@ -0,0 +1,82 @@
+************************************************************************************************************************
+运行程序
+************************************************************************************************************************
+
+========================================================================================================================
+CMake 状态栏
+========================================================================================================================
+
+如果配置成功, 在 VSCode 下方状态栏将会显示类似这样的一行:
+
+.. figure:: cmake工具列表.png
+
+此处我们只关注从 :menuselection:`ⓘ[Debug]` 起的右边部分.
+
+------------------------------------------------------------------------------------------------------------------------
+构建相关
+------------------------------------------------------------------------------------------------------------------------
+
+:menuselection:`ⓘ[Debug]`
+  当前所选择的构建配置, 指示按什么配置来生成编译程序, 点击可以切换.
+
+  .. admonition:: 不同的构建配置介绍
+    :class: dropdown
+
+    Debug
+      调试版本, 一般由程序员用于调试. 它不对代码做任何优化并且会记录代码与程序间的对应关系 (称为调试信息), 从而允许实际地逐行执行代码.
+
+    Release
+      发行版本, 即最终发布给用户的版本. 基于 as-if 规则, 它只需要保证程序运行起来就像代码看起来那样 (as-is), 因而可以对代码进行尽可能的优化.
+
+      需要注意的是, 针对程序中的有符号数溢出、下标越界等未定义行为, 它怎么优化都可以, 因而即使炸掉你的电脑也是可能的, 所以不要让代码中有未定义行为.
+
+    RelWithDebInfo
+      具有调试信息的发行版本. 由于未定义行为等的存在, 我们可能遇到调试版本能正常运行, 但发行版本出现问题的情况, 此构建配置即用于调试这种情况.
+
+      由于发行版本对代码进行优化, 调试过程中可能出现一下跳过好几行的情况, 这是正常的.
+
+    MinSizeRel
+      以最小大小为首要目标进行优化的发行版本.
+
+    **喜欢谈优化的新手请先知道有不同的构建配置; 抱怨程序慢的人请先切换到 Release 构建配置.**
+
+:menuselection:`⚒[Clang 17.0.6 arm64-...]`
+  当前选择的工具包或配置档案, 指示用什么软件来生成编译程序, 此处即 :doc:`/configure/main` 中选择的编译器 Clang.
+
+------------------------------------------------------------------------------------------------------------------------
+编译生成
+------------------------------------------------------------------------------------------------------------------------
+
+:menuselection:`⚙生成`
+  点击即可对 *当前预生成的目标* 进行编译生成.
+
+:menuselection:`[all]`
+  *当前预生成的目标*. 点击可以切换, :menuselection:`[all]` 表示编译生成所有目标.
+
+  .. figure:: cmake选择生成目标.png
+
+    点击后弹出的选择窗口, 展示目前项目中所有可用生成目标.
+
+------------------------------------------------------------------------------------------------------------------------
+运行
+------------------------------------------------------------------------------------------------------------------------
+
+:menuselection:`▶播放按钮`
+  点击即可对 *当前预运行的目标* 进行运行, 也可以用快捷键 :KBD:`Shift`:KBD:`F5` 进行运行.
+
+:menuselection:`[test]`
+  *当前预运行的目标*, 点击可以切换. 在运行前会先对 *当前预生成的目标* 和 *当前预运行的目标* 进行生成.
+
+  .. warning::
+
+    该按钮初次配置时可能不会显示, 点击一次 :menuselection:`▶播放按钮`, 在弹出的选项中随便选一个作为 *当前预运行的目标* 即可.
+
+========================================================================================================================
+运行 test
+========================================================================================================================
+
+根据上面的描述, 要运行 test, 我们将 *当前预生成的目标* 和 *当前预运行的目标* 均设置为 :menuselection:`[test]`, 点击 :menuselection:`▶播放按钮` 或按快捷键 :KBD:`Shift`:KBD:`F5` 即可.
+
+.. hint::
+
+  CMake Tools 扩展除状态栏提供的功能外, 还提供了非常多的功能, 建议通过 `VSCode CMake 拓展用户手册`_ 学习.