123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222 |
- <html>
- <head>
- <meta name="GENERATOR" content="Microsoft FrontPage 5.0">
- <meta name="ProgId" content="FrontPage.Editor.Document">
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>Filesystem issue reporting</title>
- <link href="styles.css" rel="stylesheet">
- </head>
- <body>
- <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111">
- <tr>
- <td width="277">
- <a href="../../../index.htm">
- <img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td>
- <td align="middle">
- <font size="7">Filesystem Bug Reporting</font>
- </td>
- </tr>
- </table>
- <table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse"
- bordercolor="#111111" bgcolor="#D7EEFF" width="100%">
- <tr>
- <td><a href="index.htm">Home</a>
- <a href="tutorial.html">Tutorial</a>
- <a href="reference.html">Reference</a>
- <a href="faq.htm">FAQ</a>
- <a href="release_history.html">Releases</a>
- <a href="portability_guide.htm">Portability</a>
- <a href="v3.html">V3 Intro</a>
- <a href="v3_design.html">V3 Design</a>
- <a href="deprecated.html">Deprecated</a>
- <a href="issue_reporting.html">Bug Reports </a>
- </td>
- </table>
- <p>Boost.Filesystem issues such as bug reports or feature requests should be
- reported via a <a href="https://github.com/boostorg/filesystem/issues/new">GitHub ticket</a>.</p>
- <p><a href="https://github.com/boostorg/filesystem/pulls">GitHub pull requests</a>
- are encouraged, too, although anything beyond really trivial fixes needs a
- ticket.</p>
- <h3>Bug reports</h3>
- <p>A timely response to your bug report is much more likely if <b>the problem can
- be immediately reproduced without guesswork and regression tests can be easily
- created</b>. </p>
- <p>You need to provide the following:</p>
- <ol>
- <li>A simple test program
- that:<ul>
- <li>Illustrates the problem, and</li>
- <li>Automatically yields an unambiguous pass or fail result - returning zero
- for pass and non-zero for fail is preferred, and </li>
- <li>Can be used as the basis for adding tests to Boost.Filesystem's
- regression test suite.</li>
- </ul>
- </li>
- <li>The compiler, standard library, platform, and Boost version you
- used to build and run your test program.</li>
- <li>A description of how to build and run the test program.
- </li>
- <li>A copy of the output from the test
- program, if any.</li>
- <li>An email address for follow-up questions.</li>
- </ol>
- <p>See <a href="#Rationale">Rationale</a> to find out why the above is needed.</p>
- <p>For a mostly automatic framework to provide the above, read on!</p>
- <h3>Bug reporting framework</h3>
- <p>The directory <code><boost-root>/libs/filesystem/bug></code> provides a bug test program (<code><a href="#bug-cpp">bug.cpp</a></code>)
- and a build file (<code>Jamfile.v2</code>). Here is what you need to do:</p>
- <ol>
- <li>Add one or more test cases to <code><a href="#bug-cpp">bug.cpp</a></code>
- using any text or program editor.</li>
- <li><a href="#Build-and-test">Build and test</a>.</li>
- <li>Attach copies of the <a href="#Test-output">Test output</a> and test
- program to the <a href="https://svn.boost.org/trac/boost/newticket">Trac
- ticket</a>.</li>
- </ol>
- <p>That's it! When you complete those steps, you will be done!</p>
- <p>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. </p>
- <h3>Using the framework</h3>
- <h4><a name="bug-cpp"><code>bug.cpp</code></a></h4>
- <p>Here is <code>bug.cpp</code> as supplied. To report a real bug, use
- <code>BOOST_TEST</code> and <code>BOOST_TEST_EQ</code> macros to build your own
- test cases. You can delete the three tests already in <code>bug.cpp</code>:</p>
- <blockquote>
- <pre>#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
- }
- </pre>
- </blockquote>
- <h4><a name="Build-and-test">Build and test</a></h4>
- <p>POSIX-like systems:</p>
- <blockquote>
- <pre>cd <boost-root>/libs/filesystem/bug
- ../../../b2 -a
- bin/bug</pre>
- </blockquote>
- <p>Windows:</p>
- <blockquote>
- <pre>cd <boost-root>\libs\filesystem\bug
- ..\..\..\b2 -a
- bin\bug</pre>
- </blockquote>
- <h4><a name="Test-output">Test output</a></h4>
- <p>Running the test on Windows produced this test output:</p>
- <blockquote>
- <pre>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.</pre>
- </blockquote>
- <p>The test framework runs <code>test_main()</code> from a <code>try</code>
- block with a <code>catch</code> block that reports exceptions via <code>
- std::exception what()</code>. So the output will differ if an exception is
- thrown.</p>
- <h2>Background information</h2>
- <p>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.</p>
- <h3><a name="b2-command-line-options"><code>b2</code> command line</a></h3>
- <p><code>b2</code> (formerly <code>bjam</code>) usage: <code>b2
- [options] [properties] [target]</code></p>
- <p>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:</p>
- <p><b>Options</b></p>
- <blockquote>
- <p><code>-a</code> 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.</p>
- </blockquote>
- <p><b>Properties</b></p>
- <blockquote>
- <p><code>address-model=<i>n n</i></code> is 32 or 64.
- Explicitly request either 32-bit or 64-bit code generation. This typically
- requires that your compiler is appropriately configured.</p>
- <p><code>variant=</code><i>string string </i>is
- <code>debug</code> or <code>release</code>.</p>
- <p><code>toolset=</code><i>string</i> The C++
- compiler to use. For example, <code>gcc-4.9</code>, <code>clang-3.3</code>,
- <code>or msvc-14.0</code>.</p>
- <p><code>include=</code><i>string </i>
- Additional include paths for C and C++ compilers.</p>
- <p><code>cxxflags=</code><i>string </i>
- Custom options to pass to the C++ compiler.</p>
- <p><code>define=</code><i>string</i>
- Additional macro definitions for C and C++ compilers. <i>string</i> should be
- either <code class="computeroutput">SYMBOL</code> or
- <code class="computeroutput">SYMBOL=VALUE</code></p>
- </blockquote>
- <h3><a name="Rationale">Rationale</a></h3>
- <p>Here is the request list again, with rationale added:</p>
- <ol>
- <li>A simple test program
- that:<ul>
- <li dir="ltr">
- <p dir="ltr">Illustrates the problem <b>[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.] </b>and</li>
- <li>Automatically yields an unambiguous pass or fail result - returning zero
- for pass and non-zero for fail is preferred <b>[Prevents
- miscommunications and allows use in automatic regression tests.]</b>, and </li>
- <li>Can be used as the basis for adding tests to Boost.Filesystem's
- regression test suite <b>[With good test cases fixes come easier and
- regressions become less likely]</b>.</li>
- </ul>
- </li>
- <li>The compiler, standard library, platform, and Boost version you
- used to build and run your test program. <b>[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. ]</b></li>
- <li>A description of how to build and run the test program. <b>[If b2
- (formerly known as bjam) is used as the build engine, this is not a concern,
- but otherwise much more information is needed.]</b></li>
- <li>A copy of the output from the test
- program, if any. <b>[Avoids misinterpreting results.]</b></li>
- <li>An email address for follow-up questions.<b> [Trac comments are the
- primary means of response, but it is disheartening when a trac question is not
- answered and there is no email address attached for followup.]</b></li>
- </ol>
- <hr>
- <p>Revised
- <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38902" --></p>
- <p>© Copyright Beman Dawes, 2014</p>
- <p> Distributed under the Boost Software
- License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">
- www.boost.org/LICENSE_1_0.txt</a></p>
- </body>
- </html>
|