tools update-golden 工具
============================

update-golden 工具概述
::::::::::::::::::::::::::

update-golden 是一个用于即时更新指定 maat case 仓库 golden 文件的小工具. 和 maat / nabu 的使用方式类似, 其支持
不定个数的 case, 并可以通过 -\-dir 指定要更新 golden 的 case.

update-golden 工具一般有两个作用, 但本质上都是通过自动更新 golden 文件来完成的, update-golden 工具会自动读取 tcl 文件
中用户指定的 rule 和 result / target 两个对比文件, 并尝试在 report 目录中寻找 result 文件覆盖 golden 中的 target 文件.
其适用的场景如下:

1. 当用户的 Thor 代码有更新并需要手动更新 golden 时.
2. 当用户需要查看以最新 RainaSynth 数据为 golden 时 maat 执行 case 的结果.

.. code:: bash

   # 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
   mkdir ~/repo
   # 用户编译了改动后的 RainaSynth, 在 maat 中使用并获取了最新的输出.

   # 使用 tools update-golden 更新 Sdc/../case1, Eco/../case3, Power/../case5 这三个 case, /../ 表示中间的数个子模块
   tools update-golden Sdc/../case1 Eco/../case3 Power/../case5
   # 仅更新 Sdc 这个模块下所有的 case
   tools update-golden Sdc
   # 仅更新 Sdc/mod1 这个子模块下所有的 case
   tools update-golden Sdc/mod1


   # 若当前用户位于某个 case 目录中
   cd ~/repo/case1
   # 尝试更新所有 case, 未发现 case, 检查自身是否为 case
   tools update-golden
   # 未发现其他 case, 检测出 pwd 为 case, 更新当前 case (case1)

* 使用 -\-dir 指定 cases 目录, 此时将在指定的目录下寻找 case 并更新.

.. code:: bash

   # 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
   mkdir ~/repo

   # 进入其他目录中, 使用 --dir 执行指定路径的 case
   cd ~/another_dir
   # 尝试使用指定的 dir 执行 repo 下的所有 case 并汇总输出
   tools update-golden --dir ~/repo

   # 其他用法如通配符, 指定 case 与上述示例一致
   tools update-golden --dir ~/repo case1 case3 case5 test*

update-golden 工具使用教程
::::::::::::::::::::::::::::::::

update-golden 的 help 文档如下:

.. code:: 

    [root@dev02 Thor]$ tools update-golden --help
    Usage: tools update-golden [OPTIONS] [CASE_NAMES]...

    update golden files

    Options:
    --debug
    --dir TEXT  the case dir
    --help      Show this message and exit.

--debug
-----------------

指定 tools update-golden 执行模式为 debug 模式, 在此模式下, update-golden 工具将输出详细的 result 覆盖 golden 的情况.

--dir
-----------------

指定要更新的 case 路径.

--help
-----------------

输出 update-golden 的 help 文档.