文件系统错误报告

Boost.Filesystem 问题，例如错误报告或功能请求，应该通过 GitHub工单 报告。

GitHub pull requests 也鼓励使用，尽管除了非常简单的修复之外，任何事情都需要工单。

错误报告

如果您能立即重现问题，无需猜测，并可以轻松创建回归测试，您的错误报告更有可能得到及时的回复。

您需要提供以下内容

1. 一个简单的测试程序，
   • 说明问题，并且
   • 自动产生明确的通过或失败结果 - 首选返回零表示通过，非零表示失败，并且
   • 可以作为为 Boost.Filesystem 的回归测试套件添加测试的基础。
2. 用于构建和运行测试程序的编译器、标准库、平台和 Boost 版本。
3. 关于如何构建和运行测试程序的描述。
4. 测试程序输出的副本（如果有）。
5. 用于后续问题的电子邮件地址。

请参阅 原因 以了解为何需要上述内容。

对于一个大部分自动化的框架来提供上述内容，请继续阅读！

错误报告框架

目录 <boost-root>/libs/filesystem/bug> 提供了一个错误测试程序 (bug.cpp) 和一个构建文件 (Jamfile.v2)。以下是您需要做的事情

1. 使用任何文本或程序编辑器将一个或多个测试用例添加到 bug.cpp 中。
2. 构建和测试.
3. 将 测试输出 和测试程序的副本附加到 Trac工单 上。

就是这样！完成这些步骤后，您就完成了！

测试输出提供有关编译器、标准库、平台、Boost 版本和命令行的所有基本信息，而您添加的测试用例应该使库维护者能够轻松地重现问题。

使用框架

bug.cpp

以下是提供的 bug.cpp。要报告真实错误，请使用 BOOST_TEST 和 BOOST_TEST_EQ 宏来构建您自己的测试用例。您可以删除 bug.cpp 中已经存在的三个测试。

#include <boost/detail/lightweight_test_report.hpp>
#include <boost/filesystem.hpp>

namespace fs = boost::filesystem;

int test_main(int, char*[])     // note name
{
  BOOST_TEST(2 + 2 == 5);       // one convertible-to-bool argument; this one fails!
  BOOST_TEST_EQ(4 + 4, 9);      // two EqualityComparible arguments; this one fails!
  BOOST_TEST(fs::exists("."));  // should pass, so nothing should be reported

  return ::boost::report_errors();   // required
}

构建和测试

类 POSIX 系统

cd <boost-root>/libs/filesystem/bug
../../../b2 -a
bin/bug

Windows

cd <boost-root>\libs\filesystem\bug
..\..\..\b2 -a
bin\bug

测试输出

在 Windows 上运行测试会产生此测试输出

Microsoft Visual C++ version 14.0
Dinkumware standard library version 610
Win32
Boost version 1.58.0
Command line: bin\bug
bug.cpp(10): test '2 + 2 == 5' failed in function
  'int __cdecl test_main(int,char *[])'
bug.cpp(11): test '4 + 4 == 9' failed in function
  'int __cdecl test_main(int,char *[])': '8' != '9'
2 errors detected.

测试框架从 try 块运行 test_main()，该块具有一个 catch 块，该块通过 std::exception what() 报告异常。因此，如果抛出异常，输出将有所不同。

背景信息

您现在应该拥有足够的信息来提交一个易于重现的错误报告。因此，您可以跳过阅读本页面的其余部分，除非您需要做一些非同寻常的事情。

b2 命令行

b2 (以前为 bjam) 用法：  b2 [选项] [属性] [目标]

Boost.Build b2 有许多选项、属性和目标，但您在错误报告中不需要大多数选项。以下是一些您可能会发现有用的选项

选项

-a    重新构建所有内容，而不仅仅是过时的目标。在上面的示例构建中使用它以确保库使用与测试程序相同的设置进行构建。

属性

address-model=n  n 是 32 或 64。显式请求 32 位或 64 位代码生成。这通常需要您的编译器进行适当的配置。

variant=string      string 是 debug 或 release。

toolset=string      要使用的 C++ 编译器。例如，gcc-4.9、clang-3.3、或 msvc-14.0。

include=string      C 和 C++ 编译器的额外包含路径。

cxxflags=string      传递给 C++ 编译器的自定义选项。

define=string      C 和 C++ 编译器的额外宏定义。string 应该是 SYMBOL 或 SYMBOL=VALUE

原因

以下是请求列表，添加了原因

1. 一个简单的测试程序，
   • 说明问题 [代码比散文传达得更清楚。如果看起来要花一些时间才能准确找出问题所在，或者更糟的是，可能会导致徒劳无功的搜索，那么错误报告就会被搁置一旁，待以后再处理，然后经常被遗忘。] 并且
   • 自动产生明确的通过或失败结果 - 首选返回零表示通过，非零表示失败 [防止误解，并允许在自动回归测试中使用。]，并且
   • 可以作为为 Boost.Filesystem 的回归测试套件添加测试的基础 [有了好的测试用例，修复会更容易，回归的可能性会降低]。
2. 用于构建和运行测试程序的编译器、标准库、平台和 Boost 版本。[实现包含许多平台相关代码，并且还取决于上面提到的其他因素。提前知道这些事情可以将错误报告集中起来，而无需索取更多信息。]
3. 关于如何构建和运行测试程序的描述。[如果使用 b2（以前称为 bjam）作为构建引擎，这不是问题，但在其他情况下，需要更多信息。]
4. 测试程序输出的副本（如果有）。[避免误解结果。]
5. 用于后续问题的电子邮件地址。[Trac 评论是主要回复方式，但令人沮丧的是，当 Trac 问题没有得到回复，并且没有附加电子邮件地址以供后续使用时。]

© Copyright Beman Dawes, 2014

© Copyright Andrey Semashev, 2019, 2021

根据 Boost 软件许可证版本 1.0 分发。请参阅 www.boost.org/LICENSE_1_0.txt