[PATCH] Improve FAQ answer on debugging Cygwin

[PATCH] Improve FAQ answer on debugging Cygwin

[Jon TURNEY]

Improve FAQ answer on debugging Cygwin to mention the cygwin-debuginfo package
and the gdb command 'set cygwin-exceptions oon'.

2015-08-03  Jon Turney  <jon.turney@dronecode.org.uk>

	* faq-programming.xml: Improve debugging-cygwin answer.

Signed-off-by: Jon TURNEY <jon.turney@dronecode.org.uk>
---
 winsup/doc/ChangeLog           |  4 ++++
 winsup/doc/faq-programming.xml | 26 ++++++++++++++++++++++----
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index e3eb26f..9cff0e4 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,7 @@
+2015-08-03  Jon Turney  <jon.turney@dronecode.org.uk>
+
+	* faq-programming.xml: Improve debugging-cygwin answer.
+
 2015-07-21  Corinna Vinschen  <corinna@vinschen.de>
 
 	* new-features.xml (ov-new2.2): Document sigsetjmp, siglongjmp.
diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml
index 491da5d..0c936eb 100644
--- a/winsup/doc/faq-programming.xml
+++ b/winsup/doc/faq-programming.xml
@@ -747,14 +747,32 @@ same time. Remove all but one.
 <question><para>I may have found a bug in Cygwin, how can I debug it (the symbols in gdb look funny)?</para></question>
 <answer>
 
-<para>Debugging symbols are stripped from distibuted Cygwin binaries, so any
-symbols that you see in gdb are basically meaningless. It is also a good
+<para>Debugging symbols are stripped from distibuted Cygwin binaries, so to
+debug with <command>gdb</command> you will need to install the
+<package>cygwin-debuginfo</package> package to obtain the debug symbols for
+<filename>cygwin1.dll</filename>
+</para>
+
+<para>
+If your bug causes an exception inside <filename>cygwin1.dll</filename> you will
+need to use the <command>gdb</command> command <userinput>set cygwin-exceptions
+on</userinput> to tell <command>gdb</command> to stop on exceptions inside the
+Cygwin DLL (by default they are ignored, as they may be generated during normal
+operation e.g. when checking a pointer is valid)
+</para>
+
+<para>
+It is also a good
 idea to use the latest code in case the bug has been fixed, so we
 recommend trying the latest snapshot from
-<ulink url="https://cygwin.com/snapshots/"/> or building the DLL from GIT.
+<ulink url="https://cygwin.com/snapshots/"/> or building the DLL from git.
 </para>
+
 <para>To build a debugging version of the Cygwin DLL, you will need to follow
-the instructions at <ulink url="https://cygwin.com/faq/faq.html#faq.programming.building-cygwin"/>. 
+the instructions at <ulink url="https://cygwin.com/faq/faq.html#faq.programming.building-cygwin"/>.
+</para>
+
+<para>
 You can also contact the mailing list for pointers (a simple test case that 
 demonstrates the bug is always welcome).  
 </para>
-- 
2.4.5

Re: [PATCH] Improve FAQ answer on debugging Cygwin

[Corinna Vinschen]

[-- Attachment #1: Type: text/plain, Size: 473 bytes --]

On Aug  4 13:36, Jon TURNEY wrote:
> Improve FAQ answer on debugging Cygwin to mention the cygwin-debuginfo package
> and the gdb command 'set cygwin-exceptions oon'.
> 
> 2015-08-03  Jon Turney  <...>
> 
> 	* faq-programming.xml: Improve debugging-cygwin answer.

Looks good.  Please apply.


Thanks,
Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat

[-- Attachment #2: Type: application/pgp-signature, Size: 819 bytes --]