summaryrefslogtreecommitdiff
path: root/libs/filesystem/doc/issue_reporting.html
blob: 44b80b2b67e915f11934a787aebfcca62c4196ca (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
<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> &nbsp;&nbsp;
    <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
    <a href="reference.html">Reference</a> &nbsp;&nbsp;
    <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
    <a href="release_history.html">Releases</a> &nbsp;&nbsp;
    <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
    <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
    <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
    <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
    <a href="issue_reporting.html">Bug Reports </a>&nbsp;&nbsp;
    </td>
</table>

<p>Boost.Filesystem issues such as bug reports or feature requests should be 
reported via a <a href="https://svn.boost.org/trac/boost/newticket">Boost Trac 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 trac 
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&#39;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>&lt;boost-root&gt;/libs/filesystem/bug&gt;</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&#39;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 &lt;boost/detail/lightweight_test_report.hpp&gt;
#include &lt;boost/filesystem.hpp&gt;

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 &lt;boost-root&gt;/libs/filesystem/bug
../../../b2 -a
bin/bug</pre>
</blockquote>
<p>Windows:</p>
<blockquote>
  <pre>cd &lt;boost-root&gt;\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:&nbsp; <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>&nbsp;&nbsp;&nbsp; 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&nbsp; 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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; string </i>is
  <code>debug</code> or <code>release</code>.</p>
  <p><code>toolset=</code><i>string</i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </i>
  Additional include paths for C and C++ compilers.</p>
  <p><code>cxxflags=</code><i>string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </i>
  Custom options to pass to the C++ compiler.</p>
  <p><code>define=</code><i>string</i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
  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&#39;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>&copy; 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>