• R/O
  • HTTP
  • SSH
  • HTTPS

website: Commit

HTML source code, style-sheets, scripts, and images for deployment on mingw.osdn.io


Commit MetaInfo

Revisionbe527723fb87694bfeb480cea1ca440c1a59ffdc (tree)
Zeit2021-11-20 07:58:22
AutorKeith Marshall <keith@user...>
CommiterKeith Marshall

Log Message

Publish bug reporting guidelines.

* buginfo.html: New file.
* contact.html (Reporting Bugs): Update reference text.
* faq.html docrefs.html: Add reference links.

Ändern Zusammenfassung

Diff

--- /dev/null
+++ b/buginfo.html
@@ -0,0 +1,429 @@
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 -->
--- a/contact.html
+++ b/contact.html
@@ -181,6 +181,18 @@ please use the &#8220;Preview&#8221; facility to check for,
181181 and correct, any markup errors;
182182 (these are, alas, all too common,
183183 and create a bad impression of the reporter).
184+Pay particular attention to in&#8209;line program code references,
185+or program code examples,
186+(whether in&#8209;line, or multi&#8209;line code blocks);
187+these <em>must</em>&hairsp; be enclosed in <em>triple&#8209;brace</em>&hairsp;
188+mark&#8209;up, either as <em>in&#8209;line formatted text</em>,&hairsp;
189+or as <em>formatted text blocks</em>&hairsp;, as appropriate;
190+(please see <a rel="noopener noreferrer" target="_blank"
191+ href="https://osdn.net/docs/WikiSyntax"
192+>the OSDN.net formatting guide</a>,
193+and be aware that the use of <em>fixed pitch</em>,&hairsp;
194+as introduced by <em>back&#8209;tick</em>&hairsp; mark&#8209;up,
195+generally <em>isn&#8217;t</em>&hairsp; a satisfactory alternative).
184196 Finally, when you are satisfied, click the &#8220;Submit&#8221; button
185197 to complete the ticket submission process.
186198 </p></div><!-- bug-report -->
--- a/docrefs.html
+++ b/docrefs.html
@@ -102,6 +102,9 @@ HOWTO Export a Multiple Instance Supporting C++ Class from a DLL
102102 <dt><a target="_blank" href="index.html?page=@ref@.html">
103103 HOWTO Work Around a Linker Lock-Up Problem in Windows&#8209;7
104104 </a></dt>
105+<dt><a target="_blank" href="index.html?page=buginfo.html">
106+HOWTO Submit an Effective MinGW Bug Report
107+</a></dt>
105108 </dl><!-- build -->
106109
107110 <dl class="toc overlapped" id="libs">
--- a/faq.html
+++ b/faq.html
@@ -472,6 +472,26 @@ level of optimization; (however, you should not allow this,
472472 if successful, to discourage you from reporting the issue).
473473 </p>
474474 </div><!-- answer -->
475+<button>I believe I have identified a MinGW bug; how should I report it?
476+</button>
477+<div class="answer">
478+<p>Firstly,
479+you should double check your own code,
480+to ensure that it is completely valid;
481+sadly,
482+many submitted bug reports turn out to result from user error,
483+so if you are in <em>any</em>&hairsp; doubt,
484+we recommend that you seek advice from
485+<a target="_blank" href="index.html?page=mailing.html#mingw-users"
486+>the MinGW&#8209;Users mailing list</a> community,
487+<em>before</em>&hairsp; filing a formal bug report.
488+</p>
489+<p>If you <em>do</em>&hairsp; decide to submit a formal bug report,
490+you should proceed as advised in
491+<a target="_blank" href="index.html?page=buginfo.html"
492+>these bug reporting guidelines</a>.
493+</p>
494+</div><!-- answer -->
475495 </div><!-- faq -->
476496 <div class="overlapped faq" id="portability">
477497 <h3>Software Portability Issues</h3>
Show on old repository browser