winsup/doc/gdb.sgml

   1
   2 <sect1 id="gdb"><title>Debugging Cygwin Programs</title>
   3
   4 <para>When your program doesn't work right, it usually has a "bug" in
   5 it, meaning there's something wrong with the program itself that is
   6 causing unexpected results or crashes.  Diagnosing these bugs and
   7 fixing them is made easy by special tools called
   8 <emphasis>debuggers</emphasis>.  In the case of Cygwin, the debugger
   9 is GDB, which stands for "GNU DeBugger".  This tool lets you run your
  10 program in a controlled environment where you can investigate the
  11 state of your program while it is running or after it crashes.
  12 Crashing programs sometimes create "core" files. In Cygwin these are
  13 regular text files that cannot be used directly by GDB.
  14 </para>
  15
  16 <para>Before you can debug your program, you need to prepare your
  17 program for debugging.  What you need to do is add
  18 <literal>-g</literal> to all the other flags you use when compiling
  19 your sources to objects.</para>
  20
  21 <example id="gdb-g"><title>Compiling with -g</title>
  22 <screen>
  23 <prompt>bash$</prompt> gcc -g -O2 -c myapp.c
  24 <prompt>bash$</prompt> gcc -g myapp.c -o myapp
  25 </screen>
  26 </example>
  27
  28 <para>What this does is add extra information to the objects (they get
  29 much bigger too) that tell the debugger about line numbers, variable
  30 names, and other useful things.  These extra symbols and debugging
  31 information give your program enough information about the original
  32 sources so that the debugger can make debugging much easier for
  33 you.</para>
  34
  35 <para>To invoke GDB, simply type <command>gdb myapp.exe</command> at the
  36 command prompt.  It will display some text telling you about itself,
  37 then <literal>(gdb)</literal> will appear to prompt you to enter
  38 commands.  Whenever you see this prompt, it means that gdb is waiting
  39 for you to type in a command, like <command>run</command> or
  40 <command>help</command>.  Oh <literal>:-)</literal> type
  41 <command>help</command> to get help on the commands you can type in, or
  42 read the <citation>GDB User's Manual</citation> for a complete
  43 description of GDB and how to use it.</para>
  44
  45 <para>If your program crashes and you're trying to figure out why it
  46 crashed, the best thing to do is type <command>run</command> and let
  47 your program run.  After it crashes, you can type
  48 <command>where</command> to find out where it crashed, or
  49 <command>info locals</command> to see the values of all the local
  50 variables.  There's also a <command>print</command> that lets you look
  51 at individual variables or what pointers point to.</para>
  52
  53 <para>If your program is doing something unexpected, you can use the
  54 <command>break</command> command to tell gdb to stop your program when it
  55 gets to a specific function or line number:</para>
  56
  57 <example id="gdb-break"><title>"break" in gdb</title>
  58 <screen>
  59 <prompt>(gdb)</prompt> break my_function
  60 <prompt>(gdb)</prompt> break 47
  61 </screen>
  62 </example>
  63
  64 <para>Now, when you type <command>run</command> your program will stop
  65 at that "breakpoint" and you can use the other gdb commands to look at
  66 the state of your program at that point, modify variables, and
  67 <command>step</command> through your program's statements one at a
  68 time.</para>
  69
  70 <para>Note that you may specify additional arguments to the
  71 <command>run</command> command to provide command-line arguments to
  72 your program.  These two cases are the same as far as your program is
  73 concerned:</para>
  74
  75 <example id="gdb-cliargs"><title>Debugging with command line arguments</title>
  76 <screen>
  77 <prompt>bash$</prompt> myprog -t foo --queue 47
  78
  79 <prompt>bash$</prompt> gdb myprog
  80 <prompt>(gdb)</prompt> run -t foo --queue 47
  81 </screen>
  82 </example>
  83
  84
  85 </sect1>