buginfo.html

   1 <!DOCTYPE HTML><!--
   2  *
   3  * buginfo.html
   4  *
   5  * Information and guidance to assist users in submission of
   6  * bug reports.
   7  *
   8  *
   9  * $Id$
  10  *
  11  * Written by Keith Marshall <keith@users.osdn.me>
  12  * Copyright (C) 2020, 2021, MinGW.OSDN Project
  13  *
  14  *
  15  * Redistribution and use in source and 'compiled' forms (SGML, HTML,
  16  * PDF, PostScript, RTF, etc) with or without modification, are permitted
  17  * provided that the following conditions are met:
  18  *
  19  * 1. Redistributions of source code must retain the above copyright
  20  *    notice, this list of conditions and the following disclaimer as
  21  *    the first lines of this file, unmodified.
  22  *
  23  * 2. Redistributions in compiled form (transformed to other DTDs,
  24  *    converted to PDF, PostScript, RTF and other formats) must
  25  *    reproduce the above copyright notice, this list of conditions
  26  *    and the following disclaimer in the documentation and/or other
  27  *    materials provided with the distribution.
  28  *
  29  * THIS DOCUMENTATION IS PROVIDED BY THE MINGW.OSDN PROJECT "AS IS"
  30  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  31  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  32  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE MINGW.OSDN PROJECT, OR
  33  * ITS CONTRIBUTORS, BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  34  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  36  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  37  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  38  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  39  * OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  40  * DAMAGE.
  41  *
  42  *
  43  * Note: this page assumes browser support for the following numeric
  44  * HTML entity codes:
  45  *
  46  *    &#8209;   non-breaking hyphen
  47  *    &#8216;   typographic left (opening) single quote
  48  *    &#8217;   typographic apostrophe/right (closing) single quote
  49  *    &#8220;   typographic left (opening) double quote
  50  *    &#8221;   typographic right (closing) double quote
  51  *
  52 -->
  53 <script class="masthead">
  54 /* Script fragment, to assign titles specific to this page; this is
  55  * encapsulated within the "masthead", where such titles are displayed,
  56  * to ensure that whatever page content may follow will be correctly
  57  * positioned, relative to the masthead content.
  58  */
  59  set_page("title", "Reporting Bugs");
  60  set_page("subtitle", "HOWTO Submit an Effective MinGW Bug Report");
  61 </script><!-- masthead -->
  62 <p>So you think you have found a bug and would like to report the problem?
  63 Before reporting a bug please ensure you have applied all applicable updates
  64 to your build environment, and also search the <a target="_blank"
  65  href="index.html?page=mailing.html#mingw-users"
  66 >MinGW.OSDN mail archives</a>, and the <a rel="noopener noreferrer"
  67  target="_blank" href="https://osdn.net/projects/mingw/ticket/"
  68 >MinGW.OSDN &#8220;Issues&#8221; ticket system</a>,
  69 to ensure the bug has not already been reported,
  70 or if a temporary workaround has been suggested.
  71 (When searching within the ticket system,
  72 please ensure that you include &#8220;Closed&#8221; tickets;
  73 it may be that a solution is already available,
  74 pending a future release).
  75 </p>
  76 <p>To ensure that your report will be given the utmost attention,
  77 please read and follow <a href="#guidelines">the guidelines below</a>.
  78 These are provided for your benefit,
  79 as non&#8209;compliance may result in rejection of your bug report.
  80 Although they apply, in this specific context,
  81 to reporting via <a rel="noopener noreferrer"
  82  target="_blank" href="https://osdn.net/projects/mingw/ticket/"
  83 >the MinGW.OSDN ticket system</a>,
  84 these recommendations are typical of any bug reporting process.
  85 </p>
  86
  87 <div class="overlapped" id="guidelines">
  88 <h3>Guidelines for Submission of Bug Reports</h3>
  89 <p>For general guidance on <em>How to Report Bugs Effectively</em>,
  90 you are encouraged to read <a rel="noopener noreferrer" target="_blank"
  91  href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"
  92 >this treatise by Simon Tatham</a>.
  93 Do note, however, that to report MinGW bugs,
  94 you should use the reporting facilities documented below;
  95 <strong>do not</strong> report MinGW bugs to Simon &mdash;
  96 he is unlikely to be interested.
  97 </p>
  98 <p>When reporting a bug to one of the
  99 <a target="_blank" href="index.html?page=mailing.html#mingw-users"
 100 >MinGW mailing lists</a>
 101 or to the <a rel="noopener noreferrer" target="_blank"
 102  href="https://osdn.net/projects/mingw/ticket/"
 103 >MinGW Issues ticket system on OSDN.net</a>,
 104 please include as much as possible of the following information,
 105 pertinent to the problem:
 106 </p>
 107
 108 <ul class="overlapped" id="host-info">
 109 <li><strong>Host Operating System Information and Version</strong>
 110 <p>Your build environment will probably not be the same as our defaults,
 111 so it will helpful if you give us some information about your setup;
 112 in particular, please specify which version of Windows you are using,
 113 be it Windows&#8209;95, Windows&#8209;98, Windows&#8209;ME, Windows&#8209;NT,
 114 Windows&#8209;2000, Windows&#8209;XP, Windows&#8209;Vista, Windows&#8209;7,
 115 Windows&#8209;8, Windows&#8209;8.1, or Windows&#8209;10;
 116 alternatively,
 117 if you are using a MinGW&#8209;compatible cross&#8209;compiler suite,
 118 please provide details of the system on which you are running it.
 119 </p>
 120 <p>If you are working on a native MS&#8209;Windows host,
 121 please tell us whether you are running the compiler suite from
 122 Microsoft&#8217;s <code>cmd.exe</code>,
 123 or if you are using a Bourne shell environment,
 124 such as <strong>MSYS</strong>, or <strong>Cygwin</strong>.
 125 (Do please note that modern Cygwin is effectively equivalent to
 126 the use of a cross&#8209;compiler suite, on a non&#8209;Windows host;
 127 very old Cygwin versions exhibit behavioural similarities to MSYS,
 128 but if you are still using one of these &mdash; characterized by use of
 129 the &#8216;<code>gcc -mno-cygwin ...</code>&#8217; command to enter
 130 MinGW compilation mode &mdash; you should <em>definitely</em>
 131 seek to upgrade).
 132 </p>
 133 <p>If you are using the MSYS Bourne shell,
 134 please show us the the output produced by running the command:
 135 </p>
 136 <pre class="box-out vt">$ <kbd>uname -a</kbd></pre>
 137 <p>Furthermore,
 138 if you are using RXVT as the container in which to run the MSYS shell,
 139 then please confirm that the bug is also present if you run the shell
 140 in a <em>native</em> MS&#8209;Windows console,
 141 (i.e.&nbsp;by starting MSYS with the <code>-norxvt</code> option,
 142 or by moving <code>rxvt.exe</code> out of the way,
 143 before starting MSYS).
 144 </p></li>
 145 </ul><!-- host-info -->
 146
 147 <ul class="overlapped" id="gcc-info">
 148 <li><strong>GCC Version and Configuration</strong>
 149 <p>If you are using a MinGW&#8209;GCC compiler suite,
 150 running on a native MS&#8209;Windows host system,
 151 the GCC compiler version, and configuration,
 152 can be determined by running the following command
 153 (either from Microsoft&#8217;s <code>cmd.exe</code> prompt,
 154 or from an MSYS Bourne shell prompt):
 155 </p>
 156 <pre class="box-out vt">$ <kbd>gcc -v</kbd></pre>
 157 <p>If you are using a MinGW&#8209;compatible cross&#8209;compiler,
 158 the command is effectively the same, but with &#8216;<code>gcc</code>&#8217;
 159 qualified by the appropriate host prefix;
 160 e.g.&nbsp;if your cross&#8209;compiler is characterized by
 161 the &#8216;<code>mingw32</code>&#8217; host prefix,
 162 you would invoke the equivalent of the preceding command as:
 163 <pre class="box-out vt">$ <kbd>mingw32-gcc -v</kbd></pre>
 164 <p>Regardless of which form you use to invoke it,
 165 the output from the preceding command will tell us
 166 which version of GCC you are using,
 167 whether it is operating on the basis of built&#8209;in &#8216;specs&#8217;,
 168 or it is using an external &#8216;specs&#8217; file,
 169 (of which you should provide a copy),
 170 and the options with which GCC was configured.
 171 Please post the output from this command in its entirety,
 172 (i.e.&nbsp;copy&#8209;and&#8209;paste it);
 173 <em><strong>do not</strong></em> trim,
 174 or exclude any part of it.
 175 </p></li>
 176 </ul><!-- gcc-info -->
 177
 178 <ul class="overlapped" id="binutils-info">
 179 <li><strong>GNU Binutils Version</strong>
 180 <p>The GNU binutils suite is a prerequisite of the GCC compiler suite,
 181 (providing the assembler, and linker, among other utilities).
 182 The installed version <em>must</em> be consistent with the GCC requirement;
 183 you may verify this by running the linker command:
 184 </p>
 185 <pre class="box-out vt">$ <kbd>ld -v</kbd></pre>
 186 <p>or the cross&#8209;compiler equivalent, (once again,
 187 assuming a host prefix of &#8216;<code>mingw32</code>&#8217;):
 188 </p>
 189 <pre class="box-out vt">$ <kbd>mingw32-ld -v</kbd></pre>
 190 <p>As in the case of GCC version identification,
 191 the output from this command will indicate the binutils version;
 192 please post it in its entirety,
 193 (i.e.&nbsp;copy&#8209;and&#8209;paste it);
 194 <em><strong>do not</strong></em> trim,
 195 or exclude any part of it.
 196 </p></li>
 197 </ul><!-- binutils-info -->
 198
 199 <ul class="overlapped" id="wsl-info">
 200 <li><strong>MinGW Runtime Library and Windows API Version</strong>
 201 <p>Since the majority of bugs,
 202 which are directly attributable to MinGW, will,
 203 in some way, be related to the MinGW Runtime Library,
 204 or its associated Windows API implementation,
 205 it is imperative that you tell us which versions of these
 206 you are using;
 207 these may be identified by running (in the MSYS shell):
 208 </p><pre class="box-out vt">
 209 $ <kbd>echo "#include &lt;windows.h&gt;" | gcc -E -dM -xc - | egrep "(MINGW32|W(IN|32)API)_VERSION"
 210 </kbd></pre>
 211 <p>or its equivalent with a cross&#8209;compiler suite,
 212 (with a host prefix of, e.g.&nbsp;&#8216;<code>mingw32</code>&#8217;):
 213 </p><pre class="box-out vt">
 214 $ <kbd>echo "#include &lt;windows.h&gt;" | mingw32-gcc -E -dM -xc - | egrep "(MINGW32|W(IN|32)API)_VERSION"
 215 </kbd></pre>
 216 <p>If you are running the compiler suite from Microsoft&#8217;s
 217 <code>cmd.exe</code> prompt,
 218 identification of these package versions becomes rather more awkward:
 219 </p>
 220 <ol style="margin-top: -0.3em; margin-left: -1.1em; list-style: lower-alpha">
 221 <li>Firstly &mdash;
 222 unless you have an external (third&#8209;party) implementation
 223 of <code>echo.exe</code> (or a suitable alternative),
 224 which mimics the Bourne shell interpretation of quoted arguments
 225 &mdash; the command:
 226 <pre class="box-out vt">
 227 C:\&gt; <kbd>echo "#include &lt;windows.h&gt;"</kbd>
 228 "#include &lt;windows.h&gt;"
 229 </pre>
 230 <p>will leave the enclosing quotes in place,
 231 resulting in an invalid statement to be passed through the pipe,
 232 to <code>gcc</code>.
 233 Omitting the quotes isn&#8217;t an option,
 234 because the &#8220;&lt;&#8221; and &#8220;&gt;&#8221; angle brackets,
 235 which enclose <code>&lt;windows.h&gt;</code>,
 236 will be interpreted as redirection operators,
 237 and will invalidate the syntax of the <code>echo</code> command itself:
 238 </p><pre class="box-out vt">
 239 C:\&gt; <kbd>echo #include &lt;windows.h&gt;</kbd>
 240 The syntax of the command is incorrect.
 241 </pre>
 242 <p>Escaping the angle brackets yields the required output:
 243 </p><pre class="box-out vt">
 244 C:\&gt; <kbd>echo #include ^&lt;windows.h^&gt;</kbd>
 245 #include &lt;windows.h&gt;
 246 </pre>
 247 <p>but even this isn&#8217;t sufficient,
 248 when this output is piped to <code>gcc</code>:
 249 </p><pre class="box-out vt">
 250 C:\&gt; <kbd>echo #include ^&lt;windows.h^&gt; | gcc -E -dM -xc -</kbd>
 251 The syntax of the command is incorrect.
 252 #define ...
 253 ...
 254 </pre>
 255 <p>It appears that construction of the pipeline causes
 256 the command to be parsed twice, and that the escaped angle brackets
 257 are reinterpreted as redirection operators, on the second parse.
 258 To correct this, the angle brackets must be escaped twice:
 259 </p><pre class="box-out vt">
 260 C:\&gt; <kbd>echo #include ^^^&lt;windows.h^^^&gt; | gcc -E -dM -xc -</kbd>
 261 #define ...
 262 ...
 263 </pre>
 264 </li>
 265 <li>Secondly &mdash;
 266 unless you have a third&#8209;party implementation
 267 of <code>egrep.exe</code> (or a suitable alternative) &mdash;
 268 it may be necessary to use Microsoft&#8217;s <code>find</code> command;
 269 since this does not support regular&#8209;expression matching,
 270 each version tag match requires a separate command invocation.
 271 <pre class="box-out vt">
 272 C:\&gt; <kbd>echo #include ^^^&lt;windows.h^^^&gt; | gcc -E -dM -xc - | find "MINGW32_VERSION"
 273 </kbd>#define MINGW32_VERSION ...
 274
 275 C:\&gt; <kbd>echo #include ^^^&lt;windows.h^^^&gt; | gcc -E -dM -xc - | find "W32API_VERSION"
 276 </kbd>#define W32API_VERSION ...
 277 </pre>
 278 </li>
 279 </ol>
 280 <p>Given the above limitations,
 281 emulation of the recommended Bourne shell command for
 282 identification of the installed MinGW Runtime Library version,
 283 and the associated Windows API version, from Microsoft&#8217;s <code>cmd.exe</code>,
 284 without the assistance of any third&#8209;party utility programs,
 285 may require a command sequence such as:
 286 </p><pre class="box-out vt">
 287 C:\&gt; <kbd>for %T in (MINGW32 W32API WINAPI) do @(</kbd>
 288 More? <kbd>echo #include ^^^&lt;windows.h^^^&gt; | gcc -E -dM -xc - | find "%T_VERSION"
 289 </kbd>More? <kbd>)</kbd>
 290 #define MINGW32_VERSION ...
 291 #define W32API_VERSION ...
 292 </pre>
 293 <p>which does appear to achieve the desired result,
 294 at least when run from <code>cmd.exe</code> on Windows&#8209;XP.
 295 </p></li>
 296 </ul><!-- wsl-info -->
 297
 298 <ul class="overlapped" id="sscce">
 299 <li><strong>Minimal Self-Contained Test Case</strong>
 300 <p>A simple test case is the only way to reproduce a bug,
 301 if code doesn't behave as expected or won't compile.
 302 Trim your source code to the minimal set of statements
 303 needed to demonstrate the bug,
 304 and eliminate dependencies on headers,
 305 other than those provided as components of a standard MinGW installation;
 306 (if you cannot eliminate such external header dependencies,
 307 then please consider that your bug report should,
 308 more than likely,
 309 be directed to the project providing those headers).
 310 </p>
 311 <p>Unless you are reporting a failure of MinGW to compile code,
 312 which you believe to be valid,
 313 the test case should be compilable,
 314 <em>directly from the command line</em>,
 315 using <em>only</em> tools which are provided by the MinGW Project.
 316 It should be reduced to a single compilation unit.
 317 Do not post code that has to be modified,
 318 in order to demonstrate the bug.
 319 Do not post project files requiring the use of any IDE,
 320 (<em>Integrated Development Environment</em>),
 321 even if that IDE relies on MinGW to furnish its compiler suite.
 322 </p>
 323 <p>If you <em>are</em> reporting failure to compile code,
 324 which you believe to be valid,
 325 then please double check against the relevant standards,
 326 to ensure that your code really is valid;
 327 it is, alas, all too common to see such reports,
 328 where the test case is definitively <em>invalid</em>.
 329 </p></li>
 330 </ul><!-- sscce -->
 331
 332 <ul class="overlapped" id="references">
 333 <li><strong>Documentation or References</strong>
 334 <p>If the bug is related to a missing
 335 <a target="_blank" href="index.html?page=w32api.html">MS&#8209;Windows API</a>,
 336 or <a target="_blank" href="index.html?page=mingwrt.html">MinGW Runtime</a>
 337 feature, please give us links to references and/or documentation
 338 which will facilitate the implementation of the feature.
 339 A good source of documentation is MSDN (Microsoft Developer Network).
 340 Conversely, information abstracted from any Microsoft SDK,
 341 or even from a code base published under the GNU General Public Licences,
 342 (GPL or LGPL), is not a good source;
 343 the licences governing the redistribution of such information
 344 are not compatible with MinGW's public domain paradigm,
 345 and such information is, therefore,
 346 not accepted as a basis for implementation of MinGW features.
 347 </p>
 348 <p>Please also include, in your post,
 349 the version of your mingw-runtime,
 350 (found in header file <em>_mingw.h</em>),
 351 and of w32api, (found in header file <em>w32api.h</em>).
 352 </p></li>
 353 </ul><!-- references -->
 354
 355 <ul class="overlapped" id="other-info">
 356 <li><strong>Any Other Detailed Information</strong>
 357 <p>Any other detailed information,
 358 which is pertinent to your experience with the bug,
 359 will always be appreciated and may be helpful.
 360 </p></li>
 361 </ul><!-- other-info -->
 362 </div><!-- guidelines -->
 363
 364 <div class="overlapped" id="generic-bugs">
 365 <h3>Generic Package Bugs</h3>
 366 <p>Under certain circumstances
 367 you may find a bug in a base package, such as MinGW&#8209;GCC,
 368 that is platform independent (i.e. it can be reproduced
 369 on a platform other than one running a Windows operating system).
 370 In this situation please generate a simple test case
 371 that illustrates the bug using only standard headers and libraries
 372 and submit the bug report, following the procedure detailed above,
 373 prior to submitting it to the primary maintainers.
 374 </p>
 375 <p>After receiving verification,
 376 from a MinGW developer,
 377 that the bug is indeed platform independent,
 378 please use the appropriate bug tracker or mailing list
 379 to inform the package maintainers.
 380 It is in everyone's best interest that you try to use
 381 the package maintainers' standard methods
 382 and procedures for bug submission.
 383 Avoid submitting bugs specific to a port,
 384 or application that is not a part of the primary package,
 385 to any mailing list other than the
 386 <a target="_blank" href="index.html?page=mailing.html#mingw-users"
 387 >MinGW-Users list</a>.
 388 If you are uncertain about bug submission to another package maintainer,
 389 please seek assistance on the
 390 <a target="_blank" href="index.html?page=mailing.html#mingw-users"
 391 >MinGW-Users list</a>.
 392 </p>
 393 </div><!-- generic-bugs -->
 394
 395 <div class="overlapped" id="post-report">
 396 <h3>Posting a Bug Report</h3>
 397 <p>Please post bug reports using the
 398 <a rel="noopener noreferrer" target="_blank"
 399  href="https://osdn.net/projects/mingw/ticket/"
 400 >MinGW Issues ticket system</a>,
 401 (hosted within OSDN.net's bug reporting system).
 402 You will need a <a rel="noopener noreferrer" target="_blank"
 403  href="https://osdn.net/#loginbox"
 404 >OSDN.net login</a> account to post;
 405 if you don't have one then <a rel="noopener noreferrer"
 406  target="_blank" href="https://osdn.net/account/register.php"
 407 >click here to register for one</a>.
 408 </p>
 409 <p>Please refrain from posting bug reports to the mailing list;
 410 we tend to lose track of bug reports posted there!
 411 If you have a specific question regarding making the bug report,
 412 then please use the <a target="_blank"
 413  href="index.html?page=mailing.html#mingw-users"
 414 >MinGW-Users mailing list</a>
 415 to ask.
 416 </p>
 417 </div><!-- post-report -->
 418
 419 <div class="overlapped" id="get-advice">
 420 <h3>In Case of Difficulty</h3>
 421 <p>If you have difficulty in understanding,
 422 or cannot furnish information to satisfy the above requirements,
 423 please ask for help on the <a target="_blank"
 424  href="index.html?page=mailing.html#mingw-users"
 425 >MinGW-Users mailing list</a>.
 426 </p>
 427 </div><!-- get-advice -->
 428
 429 <!-- $RCSfile$: end of file -->