mirror of
https://github.com/boostorg/filesystem.git
synced 2026-01-29 19:42:08 +00:00
182 lines
7.3 KiB
HTML
182 lines
7.3 KiB
HTML
<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://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 quick response to your bug report is much more likely if <b>the problem can
|
|
be immediately reproduced without any guesswork</b>.</p>
|
|
<p>You need to provide this:</p>
|
|
<ol>
|
|
<li>A simple test program
|
|
that automatically yields an unambiguous pass or fail result.</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.</li>
|
|
</ol>
|
|
<p>For a mostly automatic way 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
|
|
BOOST_TEST_EQ(4 + 4, 9); // two EqualityComparible arguments
|
|
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>
|
|
<hr>
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->29 December, 2014<!--webbot bot="Timestamp" endspan i-checksum="38652" --></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> |