diff options
author | Christopher Faylor <me@cgf.cx> | 2000-02-17 22:38:33 +0300 |
---|---|---|
committer | Christopher Faylor <me@cgf.cx> | 2000-02-17 22:38:33 +0300 |
commit | 1fd5e000ace55b323124c7e556a7a864b972a5c4 (patch) | |
tree | dc4fcf1e5e22a040716ef92c496b8d94959b2baa /winsup/doc/gdb.sgml | |
parent | 369d8a8fd5e887eca547bf34bccfdf755c9e5397 (diff) |
import winsup-2000-02-17 snapshot
Diffstat (limited to 'winsup/doc/gdb.sgml')
-rw-r--r-- | winsup/doc/gdb.sgml | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/winsup/doc/gdb.sgml b/winsup/doc/gdb.sgml new file mode 100644 index 000000000..732004f49 --- /dev/null +++ b/winsup/doc/gdb.sgml @@ -0,0 +1,88 @@ + +<sect1 id="gdb"><title>Debugging Cygwin Programs</title> + +<para>When your program doesn't work right, it usually has a "bug" in +it, meaning there's something wrong with the program itself that is +causing unexpected results or crashes. Diagnosing these bugs and +fixing them is made easy by special tools called +<emphasis>debuggers</emphasis>. In the case of Cygwin, the debugger +is GDB, which stands for "GNU DeBugger". This tool lets you run your +program in a controlled environment where you can investigate the +state of your program while it is running or after it crashes. +Crashing programs sometimes create "core" files. In Cygwin these are +regular text files that cannot be used directly by GDB. +</para> + +<para>Before you can debug your program, you need to prepare your +program for debugging. What you need to do is add +<literal>-g</literal> to all the other flags you use when compiling +your sources to objects.</para> + +<example><title>Compiling with -g</title> +<screen> +<prompt>$</prompt> gcc -g -O2 -c myapp.c +<prompt>$</prompt> gcc -g myapp.c -o myapp +</screen> +</example> + +<para>What this does is add extra information to the objects (they get +much bigger too) that tell the debugger about line numbers, variable +names, and other useful things. These extra symbols and debugging +information give your program enough information about the original +sources so that the debugger can make debugging much easier for +you.</para> + +<para>In Windows versions of GNUPro, GDB comes with a full-featured +graphical interface. In Cygwin Net distributions, GDB is only +available as a command-line tool. To invoke GDB, simply type +<command>gdb myapp.exe</command> at the command prompt. It will +display some text telling you about itself, then +<literal>(gdb)</literal> will appear to prompt you to enter commands. +Whenever you see this prompt, it means that gdb is waiting for you to +type in a command, like <command>run</command> or +<command>help</command>. Oh <literal>:-)</literal> type +<command>help</command> to get help on the commands you can type in, +or read the <citation>GDB User's Manual</citation> for a complete +description of GDB and how to use it.</para> + +<para>If your program crashes and you're trying to figure out why it +crashed, the best thing to do is type <command>run</command> and let +your program run. After it crashes, you can type +<command>where</command> to find out where it crashed, or +<command>info locals</command> to see the values of all the local +variables. There's also a <command>print</command> that lets you look +at individual variables or what pointers point to.</para> + +<para>If your program is doing something unexpected, you can use the +<command>break</command> command to tell gdb to stop your program when it +gets to a specific function or line number:</para> + +<example><title>"break" in gdb</title> +<screen> +<prompt>(gdb)</prompt> break my_function +<prompt>(gdb)</prompt> break 47 +</screen> +</example> + +<para>Now, when you type <command>run</command> your program will stop +at that "breakpoint" and you can use the other gdb commands to look at +the state of your program at that point, modify variables, and +<command>step</command> through your program's statements one at a +time.</para> + +<para>Note that you may specify additional arguments to the +<command>run</command> command to provide command-line arguments to +your program. These two cases are the same as far as your program is +concerned:</para> + +<example><title>Debugging with command line arguments</title> +<screen> +<prompt>$</prompt> myprog -t foo --queue 47 + +<prompt>$</prompt> gdb myprog +<prompt>(gdb)</prompt> run -t foo --queue 47 +</screen> +</example> + + +</sect1> |