docs: 优化说明文档

CMakeLists.txt

@@ -43,7 +43,11 @@ write_basic_package_version_file(
 )
 
 # install
-set(CMAKE_INSTALL_PREFIX ${HOME})
+
+# to install $HOME use:
+# cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
+message("would install to: ${CMAKE_INSTALL_PREFIX}")
+
 install(FILES ${HPP_HEADER}
     DESTINATION "include/couttast"
 )
@@ -52,6 +56,10 @@ install(TARGETS tast_main
     DESTINATION "lib"
 )
 
+install(TARGETS tast_drive
+    DESTINATION "bin"
+)
+
 install(FILES
     ${CMAKE_CURRENT_BINARY_DIR}/couttastConfig.cmake
     ${CMAKE_CURRENT_BINARY_DIR}/couttastConfigVersion.cmake

example/CMakeLists.txt

@@ -21,6 +21,10 @@ add_library(tast-basiccpp SHARED
     basiccpp-udyso/tast_main.cpp
 )
 
+add_executable(simplest.exe
+    simplest/main.cpp
+)
+
 add_executable(tastself.exe
     #tastself/main.cpp
     tastself/t_logprint.cpp

example/simplest/main.cpp

@@ -5,7 +5,7 @@ int main(int argc, char** argv)
     return RUN_TAST(argc, argv);
 }
 
-DEF_TAST(test_sizoef, "测试类型大小")
+DEF_TAST(test_name, "测试用例说明")
 {
     COUT(sizeof(int));
     COUT(sizeof(int), 4);

readme.md

@@ -13,10 +13,10 @@
 ## 使用方法最简示例
 
 只需在测试文件中包含 `tinytast.hpp` 头文件，然后用 `DEF_TAST` 定义一系列类似
-`void()` 函数的代码块，其中可用 `COUT` 输出或比较感兴趣的值。
+`void()` 函数的代码块，其中可用 `COUT` 输出或比较感兴趣的值，最后在 `main()`
+函数中调用 `RUN_TAST` 。
 
 ```cpp
-// test-file1.cpp
 #include "tinytast.hpp"
 
 DEF_TAST(test_name, "测试用例说明")
@@ -25,27 +25,38 @@ DEF_TAST(test_name, "测试用例说明")
     COUT(sizeof(int), 4);
     COUT(sizeof(int)==4, true);
 }
-```
-
-在 `main()` 只要调用 `RUN_TAST` 宏即可。
-
-```cpp
-// main.cpp
-#include "tinytast.hpp"
 
 int main(int argc, char** argv)
 {
     return RUN_TAST(argc, argv);
 }
 ```
 
-将相关测试 `*.cpp` 源文件编译链接在一起即可运行。
+编译、运行大约有如下输出：其中 `COUT` 单参数时只观察结果，双参数时比较结果并给
+出正确或通过与否的判据，然后有额外统计汇总信息。
+
+```
+## run test_name()
+|| sizeof(int) =~? 4
+|| sizeof(int) =~? 4 [OK]
+|| sizeof(int)==4 =~? ture [OK]
+<< [PASS] test_name within 81 us
+
+## Summary
+<< [PASS] 1
+<< [FAIL] 0
+```
+
+可以由多个测试 `*.cpp` 源文件编译链接在一起，当然只能有一个 `main()` 定义。 
 
-另注：[v0.1](https://github.com/lymslive/couttast/tree/v0.1) 简易版不支持
+另注：[v0.1](https://github.com/lymslive/couttast/tree/v0.1) 极简版不支持
 `DEF_TAST` 定义用例及 `RUN_TAST` 运行用例。只支持 `TAST` 调用普通 `void()` 函
 数。
 
-## 构建与示例
+## 构建指引
+
+只用头文件的话，其实不需要特别地构建。但本仓库也提供了一些可运行示例及浅封装库，
+可用 `make` 简单构建，除了 C++ 标准库没有其他第三库依赖。
 
 ```bash
 make
@@ -55,15 +66,30 @@ make example
 在本仓库主目录上提供了 `makefile` ，直接 `make` 会生成 `lib/` 与 `bin/` 子目录。
 但这不是必须的，用户可以直接只使用 `include` 的头文件。
 
-也提供了 `cmake` 构造系统，例如可如下构建与安装：
+### 用 CMake 构建
+
+也提供了 `cmake` 构建系统，例如可如下构建与安装：
 
 ```bash
 mkdir build
 cd build
-cmake ..
+cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
+make
+make test
 make install
 ```
 
+用 `cmake` 工具时，按惯例构建工作在单独的 `build/` 子目录下进行。最后一步安装
+至个人 `$HOME` 下的几个子目录，`include/couttast` 、`lib/` 与 `bin/` ，这是为
+了避免 `/usr/local` 的写权限限制。
+
+如果在前面步骤 `cmake ..` 时不加 `CMAKE_INSTALL_PREFIX` 选项参数，则默认安装至
+系统目录 `/usr/local` 。安装至系统目录后，在写具体的单元测试程序时可直接使用，
+或集成至其他 CMake 构建的项目。如果安装在 `$HOME` 目录或其他目录，则可能需要在
+构建单元测试程序时调整相应的编译参数。
+
+### 构建单元测试程序
+
 有三种方法构建可执行测试程序（命令行程序），可参见 `example/basiccpp-*` 的几个子目录。
 
 1. 自己写 `main` 函数。可以在调用 `RUN_TAST` 之前作些特殊的预处理。
@@ -73,17 +99,20 @@ make install
    终调用 `RUN_TAST` 宏。然后用 `bin/tast_drive` 程序驱动编译的测试动态库，
    将动态库作为第一个命令行参数，剩余参数会传给内部的测试库。
 
+单元测试驱动单元测试动态链接库的使用方式如下：
+
 ```bash
 bin/tast_drive libmytast.so --list
 bin/tast_drive libmytast.so [test_name_fileter]
 ```
 
 注意加载动态库可能要导出环境变量 `$LD_LIBRARY_PATH`，毕竟一般不会将测试动态库
-放到系统路径中。
+放到系统路径中。因为动态链接库的方式比较复杂，也更多陷阱，在没特殊需求时，建议
+使用前两种方法构建独立可运行的单元测试程序。
 
 本测试库所支持的命令行参数见后文。
 
-## 宏定义详解
+## 单元测试库宏定义详解
 
 ### COUT 语句宏
 
@@ -129,20 +158,24 @@ COUT(abs(expr-expect) <= limit, true);
 ### TAST 宏定义与自动测试
 
 * `DEF_TAST(case_name, desc)`：相当于测试函数 `void tast_case()` 加强版，还可
-以为该测试用例附加一段描叙说明。本质上是定义了一个类及其实例。随后的 `{}` 代
+以为该测试用例附加一段描叙说明。本质上是定义了一个类及其单例。随后的 `{}` 代
 码块是该类的一个虚函数实现。
 * `RUN_TAST()`：自动执行由 `DEF_TAST` 定义的所有测试用例，且按测试名的字典序依
 次执行。可以传入 `(argc, argv)` 命令行参数，以筛选执行特定的测试用例。
 
 在定义测试用例时，参数 `case_name` 要求是合法的 C++ 符号（不加双引号），`desc` 是
-任意描叙字符串（加引号）。描叙参数也可省略，但建议加上便于人工管理测试用例。
+任意描叙字符串（加双引号）。描叙参数也可省略，但建议加上便于人工管理测试用例。
 
 在运行测试用例时，`RUN_TAST()`最后会自动调用 `TAST_RESULT` 宏，返回的是失败用
 例个数，可直接当作 `main` 的返回值， `0`表示测试成功。
 
-## 命令行参数解析
+## 单元测试程序用法
+
+当利用本单元测试库构建出可执行的单元测试程序后，有一些用法值得注意。
+
+### 命令行参数解析
 
-当多个输入的命令行参数传给 `RUN_TAST()` 时，除特定选项外，将依次对其解析：
+当将多个输入的命令行参数传给 `RUN_TAST()` 时，除特定选项外，将依次对其解析：
 
 * 如果参数完全匹配某个测试名，则只运行该用例。
 * 如果参数仅是单字符，则只运行以该字符开头的用例。
@@ -153,7 +186,11 @@ COUT(abs(expr-expect) <= limit, true);
 这些规则应该符合直觉与方便使用。暂不打算支持完整正则表达式，以保证库的轻量化。
 
 已知 bug （特性），多个命令参数筛选的测试用例没有互斥与唯一性。即在非用例全名
-的情况下，有可能多次查找到同一个用例，重复运行。
+的情况下，有可能多次匹配到同一个用例，重复运行。
+
+最典型的用法时不带任何参数运行所有测试用例，以及带上全名单测某一个或几个测试用
+例。良好的单元测试用例设计，应该使每一个单元测试可独立运行，不依赖其他用例的特
+定顺序，重复运行也应没有副作用。
 
 作为选项的命令行参数，都以一个或多个 `-` 开头，如果选项有参数，只能用 `=` 分隔
 选项名及其参数，即形如 `--key` 或 `--key=val` 格式。不支持用空格分隔（否则会当
@@ -177,7 +214,7 @@ COUT(abs(expr-expect) <= limit, true);
 ./tast_program --list | grep something
 ```
 
-## diff 模拟回归测试
+### diff 模拟回归测试
 
 ```bash
 ./tast_program > tast.cout
@@ -188,11 +225,13 @@ diff tast.cout tast.bout
 ```
 
 可将不同时段的测试输出保存文件，用 diff 比较法模拟回归测试。不过此法要注
-意的是测试中不宜输出指针地址，因为不同运行时内存地址不可能做到保持一致。另外，
-如果测试代码中只用到双参数 `COUT` 测试，一般看统计结果全部通过即可。diff 比较
+意的是测试中不宜输出指针地址，因为不同运行时内存地址不可能做到保持一致。
+
+另外，如果测试代码中主要用到双参数 `COUT` 测试，一般看统计结果全部通过达到回归
+测试的目的。即修改程序后，原来通过的单元测试用例集，应该仍保持通过。diff 比较
 法更适用于测试代码中大量使用单参数 `COUT` 不能自动判断通过与否的情况。
 
-## 性能测试 
+### 性能测试 
 
 利用宏 `TIME_TAST` 可以简便快捷地进行性能测试。它可以重复运行由 `DEF_TAST` 定
 义的某个测试用例若干次，统计每次的运行时间，并求平均值。每次运行时会调用 `sleep`
@@ -220,3 +259,23 @@ diff tast.cout tast.bout
 但是可以利用 `TIME_TAST` 的返回值，比较两个算法实现的相对大小，也就能期望预测
 一种算法比另一种更快。
 
+## 历史版本及主要变更记录
+
+### v0.2
+
+核心文件：`tinytast.hpp` 。
+
+单头文件简易版。增加了 `DEF_TAST` 宏定义测试用例，在 `main()` 入口函数只需用
+`RUN_TAST` 自动调用所有被定义的测试用例。可用命令参数指定筛选运行部分测试用例，
+并安排测试顺序。内部采用一个全局单例对象管理所有测试用例，每个 `DEF_TAST` 的用
+例除了名称与可选描叙外，函数体可按普通 `void` 函数编写，用 `COUT` 宏比较结果。
+
+提供一些应用示例，及简单驱动程序或封装库，支持 `make` 与 `cmake` 构建。
+
+### v0.1
+
+核心文件：`tast_util.hpp` 。
+
+极简速成版。除了 `COUT` 比较观察宏外，只定义了 `TAST` 宏调用普通 `void` 函数，
+用 `TAST_RESULT` 宏汇报结果。没有专门语法定义测试用例，需在 `main()` 函数中手
+动调用作为用例的 `void` 函数或用 `TAST` 宏封装调用。