ceph/src/boost/libs/filesystem/doc/issue_reporting.html

   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> &nbsp;&nbsp;
  28     <a href="tutorial.html">Tutorial</a> &nbsp;&nbsp;
  29     <a href="reference.html">Reference</a> &nbsp;&nbsp;
  30     <a href="faq.htm">FAQ</a> &nbsp;&nbsp;
  31     <a href="release_history.html">Releases</a> &nbsp;&nbsp;
  32     <a href="portability_guide.htm">Portability</a> &nbsp;&nbsp;
  33     <a href="v3.html">V3 Intro</a> &nbsp;&nbsp;
  34     <a href="v3_design.html">V3 Design</a> &nbsp;&nbsp;
  35     <a href="deprecated.html">Deprecated</a> &nbsp;&nbsp;
  36     <a href="issue_reporting.html">Bug Reports </a>&nbsp;&nbsp;
  37     </td>
  38 </table>
  39
  40 <p>Boost.Filesystem issues such as bug reports or feature requests should be
  41 reported via a <a href="https://svn.boost.org/trac/boost/newticket">Boost Trac ticket</a>.</p>
  42 <p><a href="https://github.com/boostorg/filesystem/pulls">GitHub pull requests</a>
  43 are encouraged, too, although anything beyond really trivial fixes needs a trac
  44 ticket.</p>
  45 <h3>Bug reports</h3>
  46 <p>A timely response to your bug report is much more likely if <b>the problem can
  47 be immediately reproduced without  guesswork and regression tests can be easily
  48 created</b>. </p>
  49 <p>You need to provide the following:</p>
  50 <ol>
  51   <li>A simple test program
  52 that:<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&#39;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>&lt;boost-root&gt;/libs/filesystem/bug&gt;</code> provides a bug test program (<code><a href="#bug-cpp">bug.cpp</a></code>)
  72 and 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&#39;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
  83 library, platform, Boost version, and command line, and the test cases you have
  84 added 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
  89 test cases. You can delete the three tests already in <code>bug.cpp</code>:</p>
  90 <blockquote>
  91   <pre>#include &lt;boost/detail/lightweight_test_report.hpp&gt;
  92 #include &lt;boost/filesystem.hpp&gt;
  93
  94 namespace fs = boost::filesystem;
  95
  96 int 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 &lt;boost-root&gt;/libs/filesystem/bug
 114 ../../../b2 -a
 115 bin/bug</pre>
 116 </blockquote>
 117 <p>Windows:</p>
 118 <blockquote>
 119   <pre>cd &lt;boost-root&gt;\libs\filesystem\bug
 120 ..\..\..\b2 -a
 121 bin\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
 133 Dinkumware standard library version 610
 134 Win32
 135 Boost version 1.58.0
 136 Command line: bin\bug
 137 bug.cpp(10): test '2 + 2 == 5' failed in function
 138   'int __cdecl test_main(int,char *[])'
 139 bug.cpp(11): test '4 + 4 == 9' failed in function
 140   'int __cdecl test_main(int,char *[])': '8' != '9'
 141 2 errors detected.</pre>
 142 </blockquote>
 143 <p>The test framework runs <code>test_main()</code> from a <code>try</code>
 144 block with a <code>catch</code> block that reports exceptions via <code>
 145 std::exception what()</code>. So the output will differ if an exception is
 146 thrown.</p>
 147 <h2>Background information</h2>
 148 <p>You should now have enough information to file an easy-to-reproduce bug
 149 report. So you can skip reading the rest of this page unless you need to do
 150 something 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:&nbsp; <code>b2
 153 [options] [properties] [target]</code></p>
 154 <p>Boost.Build b2 has many options, properties, and targets, but you will not
 155 need 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>&nbsp;&nbsp;&nbsp; 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&nbsp; 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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; string </i>is
 168   <code>debug</code> or <code>release</code>.</p>
 169   <p><code>toolset=</code><i>string</i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 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&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </i>
 173   Additional include paths for C and C++ compilers.</p>
 174   <p><code>cxxflags=</code><i>string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </i>
 175   Custom options to pass to the C++ compiler.</p>
 176   <p><code>define=</code><i>string</i>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 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
 185 that:<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&#39;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>&copy; Copyright Beman Dawes, 2014</p>
 217 <p> Distributed under the Boost Software
 218 License, Version 1.0. See <a href="http://www.boost.org/LICENSE_1_0.txt">
 219 www.boost.org/LICENSE_1_0.txt</a></p>
 220
 221
 222 </body>
 223
 224 </html>