OSDN Git Service

Publish MinGW installation and maintenance guidelines.
[mingw/website.git] / buginfo.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  *
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>
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>
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 -->
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 -->
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 -->
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 ...
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 -->
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 -->
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 -->
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 -->
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 -->
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 -->
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 -->
429 <!-- $RCSfile$: end of file -->