Filesystem Bug Reporting |
Home Tutorial Reference FAQ Releases Portability V3 Intro V3 Design Deprecated Bug Reports |
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:
See Rationale to find out why the above is needed.
For a mostly automatic framework to provide the above, read on!
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:
bug.cpp
using any text or program editor.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.
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; 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-like systems:
cd <boost-root>/libs/filesystem/bug ../../../b2 -a bin/bug
Windows:
cd <boost-root>\libs\filesystem\bug ..\..\..\b2 -a bin\bug
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.
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 lineb2
(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:
Options
-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.
Properties
address-model=n 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 string isdebug
orrelease
.
toolset=
string The C++ compiler to use. For example,gcc-4.9
,clang-3.3
,or msvc-14.0
.
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 eitherSYMBOL
orSYMBOL=VALUE
Here is the request list again, with rationale added:
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
Revised 28 January, 2015
© Copyright Beman Dawes, 2014
Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt