Issue Reporting

Bug Reporting Framework
Using the Framework
Rationale

Boost.Filesystem issues such as bug reports or feature requests should be reported via a GitHub ticket.

GitHub pull requests are encouraged, too, although anything beyond really trivial fixes needs a ticket.

A timely response to your bug report is much more likely if the problem can be immediately reproduced without guesswork and regression tests can be easily created.

You need to provide the following:

A simple test program that:
- Illustrates the problem, and
- Automatically yields an unambiguous pass or fail result - returning zero for pass and non-zero for fail is preferred, and
- Can be used as the basis for adding tests to Boost.Filesystem's regression test suite.
The compiler, standard library, platform, and Boost version you used to build and run your test program.
A description of how to build and run the test program.
A copy of the output from the test program, if any.

See Rationale to find out why the above is needed.

For a mostly automatic framework to provide the above, read on!

Bug Reporting Framework

The directory boost-root/libs/filesystem/bug provides a bug test program (bug.cpp) and a build file (Jamfile.v2). Here is what you need to do:

Add one or more test cases to bug.cpp using any text or program editor.
Build and test.
Attach copies of the Test output and test program to the GitHub ticket.

That's it! When you complete those steps, you will be done!

The test output supplies all of the basic information about the compiler, std library, platform, Boost version, and command line, and the test cases you have added should make it easy for the library maintainer to reproduce the problem.

Using the Framework

bug.cpp
Build and Test
Test Output
Background Information

`bug.cpp`

Here is bug.cpp as supplied. To report a real bug, use BOOST_TEST and BOOST_TEST_EQ macros to build your own test cases. You can delete the three tests already in 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
    BOOST_TEST_EQ(4 + 4, 9);     // two EqualityComparible arguments
    BOOST_TEST(fs::exists(".")); // should pass, so nothing reported

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

Build and Test

POSIX-like systems	Microsoft Windows
cd <boost-root>/libs/filesystem/bug ../../../b2 -a bin/bug	cd <boost-root>\libs\filesystem\bug ..\..\..\b2 -a bin\bug

Test Output

Running the test on Windows produced this test output:

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.

The test framework runs test_main() from a try block with a catch block that reports exceptions via std::exception::what(). So the output will differ if an exception is thrown.

Background Information

b2 Command Line

You should now have enough information to file an easy-to-reproduce bug report. So you can skip reading the rest of this page unless you need to do something a bit out of the ordinary.

`b2` Command Line

b2 (formerly bjam) usage:

b2 [options] [properties] [target]

Boost.Build b2 has many options, properties, and targets, but you will not need most of them for bug reporting. Here are a few you might find helpful:

Table 1.5. b2 Options

Option	Effect
-a	Rebuild everything rather than just out-of-date targets. Used in the example build above to ensure libraries are built with the same setup as the test program.

Table 1.6. b2 Properties

Property	Effect
address-model=n where n is 32 or 64.	Explicitly request either 32-bit or 64-bit code generation. This typically requires that your compiler is appropriately configured.
variant=string where string is `debug` or `release`.	Request debug or release build.
toolset=string where string is composed of the compiler name and optionally, a version.	The C++ compiler to use. For example, `gcc`, `gcc-4.9`, `clang-3.3`, or `msvc-14.0`. If the version is imitted, the default compiler version is used.
include=string	Additional include paths for C and C++ compilers.
cxxflags=string	Custom options to pass to the C++ compiler.
define=string	Additional macro definitions for C and C++ compilers. string should be either `SYMBOL` or `SYMBOL=VALUE`

Rationale

Here is the request list again, with rationale added:

A simple test program that:
- Illustrates the problem [Code communicates more clearly than prose. If it looks like it will it will take some time to figure out exactly what the problem is, or worse yet, might result in a wild-goose chase, the bug report gets set aside to be worked on later and then is often forgotten.] and
- Automatically yields an unambiguous pass or fail result - returning zero for pass and non-zero for fail is preferred [Prevents miscommunications and allows use in automatic regression tests.], and
- Can be used as the basis for adding tests to Boost.Filesystem's regression test suite [With good test cases fixes come easier and regressions become less likely].
The compiler, standard library, platform, and Boost version you used to build and run your test program. [The implementation includes much platform dependent code, and also depends on the other factors mentioned. Know these things upfront brings the bug report into focus without having to ask for more information.]
A description of how to build and run the test program. [If b2 (formerly known as bjam) is used as the build engine, this is not a concern, but otherwise much more information is needed.]
A copy of the output from the test program, if any. [Avoids misinterpreting results.]