1<html> 2 3<head> 4<meta name="GENERATOR" content="Microsoft FrontPage 5.0"> 5<meta name="ProgId" content="FrontPage.Editor.Document"> 6<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 7<title>Filesystem issue reporting</title> 8<link href="styles.css" rel="stylesheet"> 9</head> 10 11<body> 12 13<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111"> 14 <tr> 15 <td width="277"> 16<a href="../../../index.htm"> 17<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td> 18 <td align="middle"> 19 <font size="7">Filesystem Bug Reporting</font> 20 </td> 21 </tr> 22</table> 23 24<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" 25 bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> 26 <tr> 27 <td><a href="index.htm">Home</a> 28 <a href="tutorial.html">Tutorial</a> 29 <a href="reference.html">Reference</a> 30 <a href="faq.htm">FAQ</a> 31 <a href="release_history.html">Releases</a> 32 <a href="portability_guide.htm">Portability</a> 33 <a href="v3.html">V3 Intro</a> 34 <a href="v3_design.html">V3 Design</a> 35 <a href="deprecated.html">Deprecated</a> 36 <a href="issue_reporting.html">Bug Reports </a> 37 </td> 38</table> 39 40<p>Boost.Filesystem issues such as bug reports or feature requests should be 41reported via a <a href="https://github.com/boostorg/filesystem/issues/new">GitHub ticket</a>.</p> 42<p><a href="https://github.com/boostorg/filesystem/pulls">GitHub pull requests</a> 43are encouraged, too, although anything beyond really trivial fixes needs a 44ticket.</p> 45<h3>Bug reports</h3> 46<p>A timely response to your bug report is much more likely if <b>the problem can 47be immediately reproduced without guesswork and regression tests can be easily 48created</b>. </p> 49<p>You need to provide the following:</p> 50<ol> 51 <li>A simple test program 52that:<ul> 53 <li>Illustrates the problem, and</li> 54 <li>Automatically yields an unambiguous pass or fail result - returning zero 55 for pass and non-zero for fail is preferred, and </li> 56 <li>Can be used as the basis for adding tests to Boost.Filesystem's 57 regression test suite.</li> 58 </ul> 59 </li> 60 <li>The compiler, standard library, platform, and Boost version you 61 used to build and run your test program.</li> 62 <li>A description of how to build and run the test program. 63 </li> 64 <li>A copy of the output from the test 65 program, if any.</li> 66 <li>An email address for follow-up questions.</li> 67</ol> 68<p>See <a href="#Rationale">Rationale</a> to find out why the above is needed.</p> 69<p>For a mostly automatic framework to provide the above, read on!</p> 70<h3>Bug reporting framework</h3> 71<p>The directory <code><boost-root>/libs/filesystem/bug></code> provides a bug test program (<code><a href="#bug-cpp">bug.cpp</a></code>) 72and a build file (<code>Jamfile.v2</code>). Here is what you need to do:</p> 73<ol> 74 <li>Add one or more test cases to <code><a href="#bug-cpp">bug.cpp</a></code> 75 using any text or program editor.</li> 76 <li><a href="#Build-and-test">Build and test</a>.</li> 77 <li>Attach copies of the <a href="#Test-output">Test output</a> and test 78 program to the <a href="https://svn.boost.org/trac/boost/newticket">Trac 79 ticket</a>.</li> 80</ol> 81<p>That's it! When you complete those steps, you will be done!</p> 82<p>The test output supplies all of the basic information about the compiler, std 83library, platform, Boost version, and command line, and the test cases you have 84added should make it easy for the library maintainer to reproduce the problem. </p> 85<h3>Using the framework</h3> 86<h4><a name="bug-cpp"><code>bug.cpp</code></a></h4> 87<p>Here is <code>bug.cpp</code> as supplied. To report a real bug, use 88<code>BOOST_TEST</code> and <code>BOOST_TEST_EQ</code> macros to build your own 89test cases. You can delete the three tests already in <code>bug.cpp</code>:</p> 90<blockquote> 91 <pre>#include <boost/detail/lightweight_test_report.hpp> 92#include <boost/filesystem.hpp> 93 94namespace fs = boost::filesystem; 95 96int test_main(int, char*[]) // note name 97{ 98 BOOST_TEST(2 + 2 == 5); // one convertible-to-bool argument; this one fails! 99 BOOST_TEST_EQ(4 + 4, 9); // two EqualityComparible arguments; this one fails! 100 BOOST_TEST(fs::exists(".")); // should pass, so nothing should be reported 101 102 return ::boost::report_errors(); // required 103} 104</pre> 105</blockquote> 106<h4><a name="Build-and-test">Build and test</a></h4> 107 108 109<p>POSIX-like systems:</p> 110 111 112<blockquote> 113 <pre>cd <boost-root>/libs/filesystem/bug 114../../../b2 -a 115bin/bug</pre> 116</blockquote> 117<p>Windows:</p> 118<blockquote> 119 <pre>cd <boost-root>\libs\filesystem\bug 120..\..\..\b2 -a 121bin\bug</pre> 122</blockquote> 123<h4><a name="Test-output">Test output</a></h4> 124 125 126<p>Running the test on Windows produced this test output:</p> 127 128 129<blockquote> 130 131 132<pre>Microsoft Visual C++ version 14.0 133Dinkumware standard library version 610 134Win32 135Boost version 1.58.0 136Command line: bin\bug 137bug.cpp(10): test '2 + 2 == 5' failed in function 138 'int __cdecl test_main(int,char *[])' 139bug.cpp(11): test '4 + 4 == 9' failed in function 140 'int __cdecl test_main(int,char *[])': '8' != '9' 1412 errors detected.</pre> 142</blockquote> 143<p>The test framework runs <code>test_main()</code> from a <code>try</code> 144block with a <code>catch</code> block that reports exceptions via <code> 145std::exception what()</code>. So the output will differ if an exception is 146thrown.</p> 147<h2>Background information</h2> 148<p>You should now have enough information to file an easy-to-reproduce bug 149report. So you can skip reading the rest of this page unless you need to do 150something a bit out of the ordinary.</p> 151<h3><a name="b2-command-line-options"><code>b2</code> command line</a></h3> 152<p><code>b2</code> (formerly <code>bjam</code>) usage: <code>b2 153[options] [properties] [target]</code></p> 154<p>Boost.Build b2 has many options, properties, and targets, but you will not 155need most of them for bug reporting. Here are a few you might find helpful:</p> 156<p><b>Options</b></p> 157<blockquote> 158 <p><code>-a</code> Rebuild everything rather than 159 just out-of-date targets. Used in the example build above to ensure libraries 160 are built with the same setup as the test program.</p> 161</blockquote> 162<p><b>Properties</b></p> 163<blockquote> 164 <p><code>address-model=<i>n n</i></code> is 32 or 64. 165 Explicitly request either 32-bit or 64-bit code generation. This typically 166 requires that your compiler is appropriately configured.</p> 167 <p><code>variant=</code><i>string string </i>is 168 <code>debug</code> or <code>release</code>.</p> 169 <p><code>toolset=</code><i>string</i> The C++ 170 compiler to use. For example, <code>gcc-4.9</code>, <code>clang-3.3</code>, 171 <code>or msvc-14.0</code>.</p> 172 <p><code>include=</code><i>string </i> 173 Additional include paths for C and C++ compilers.</p> 174 <p><code>cxxflags=</code><i>string </i> 175 Custom options to pass to the C++ compiler.</p> 176 <p><code>define=</code><i>string</i> 177 Additional macro definitions for C and C++ compilers. <i>string</i> should be 178 either <code class="computeroutput">SYMBOL</code> or 179 <code class="computeroutput">SYMBOL=VALUE</code></p> 180</blockquote> 181<h3><a name="Rationale">Rationale</a></h3> 182<p>Here is the request list again, with rationale added:</p> 183<ol> 184 <li>A simple test program 185that:<ul> 186 <li dir="ltr"> 187 <p dir="ltr">Illustrates the problem <b>[Code communicates more clearly than 188 prose. If it looks like it will it will take some time to figure out exactly what the 189 problem is, or worse yet, might result in a wild-goose chase, the bug report 190 gets set aside to be worked on later and then is often forgotten.] </b>and</li> 191 <li>Automatically yields an unambiguous pass or fail result - returning zero 192 for pass and non-zero for fail is preferred <b>[Prevents 193 miscommunications and allows use in automatic regression tests.]</b>, and </li> 194 <li>Can be used as the basis for adding tests to Boost.Filesystem's 195 regression test suite <b>[With good test cases fixes come easier and 196 regressions become less likely]</b>.</li> 197 </ul> 198 </li> 199 <li>The compiler, standard library, platform, and Boost version you 200 used to build and run your test program. <b>[The implementation includes much 201 platform dependent code, and also depends on the other factors mentioned. Know 202 these things upfront brings the bug report into focus without having to ask 203 for more information. ]</b></li> 204 <li>A description of how to build and run the test program. <b>[If b2 205 (formerly known as bjam) is used as the build engine, this is not a concern, 206 but otherwise much more information is needed.]</b></li> 207 <li>A copy of the output from the test 208 program, if any. <b>[Avoids misinterpreting results.]</b></li> 209 <li>An email address for follow-up questions.<b> [Trac comments are the 210 primary means of response, but it is disheartening when a trac question is not 211 answered and there is no email address attached for followup.]</b></li> 212</ol> 213<hr> 214<p>Revised 215<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->28 January, 2015<!--webbot bot="Timestamp" endspan i-checksum="38902" --></p> 216<p>© Copyright Beman Dawes, 2014</p> 217<p> Distributed under the Boost Software 218License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt"> 219www.boost.org/LICENSE_1_0.txt</a></p> 220 221</body> 222</html> 223
