Debugging Your App (GDB)

5.2. How to Debug Your App (Using GDB)

Running your app under debugger control allows you to set breakpoints, inspect variables, view the call stack, and step through code line-by-line. This can be done with the GNU Debugger (GDB) over SSH.

Prerequisites:

• Jailbroken Device: Direct on-device debugging with GDB requires your device to be jailbroken (see 4. (Optional) Jailbreaking Your Device).

Steps for Debugging with GDB:

1. Install Debugger Package:

   • The GDB debugger package is provided with Darwin Build Environment. Locate it in the Debugger directory of your installation.

   • Install this package on your jailbroken iOS device (e.g., by transferring the .deb file and installing it via Filza/iFile or dpkg -i <package_name>.deb over SSH).

2. Configure Project for Debug Symbols:

   • Edit your project's make.cmd file.

   • Ensure the DBE_CFLAGS (or DBE_CPPFLAGS for general flags) line includes:

     • -O0 (Dash, capital letter O, number zero): Disables optimizations.

     • -g: Generates debug information.

   • Example:

     rem # Define here the compile options and the linker options for your project.
     rem # CPPFLAGS are compiler flags that will be applied to all source file types.
     rem # CFLAGS are compiler flags that will affect C and Objective-C source files,
     rem # whereas CXXFLAGS will affect C++ and Objective-C++ source files only.
     rem # If you want debug symbols to use with gdb, replace "-O2" with "-O0 -g".
     set DBE_CPPFLAGS=-W -Wall -Wno-unused-parameter -O0 -g
     set DBE_CFLAGS=
     set DBE_CXXFLAGS=
     set DBE_LDFLAGS=

3. Rebuild Your Project:

   • After modifying make.cmd, rebuild your project.

   • A new YourAppName.DEBUG directory should be created in your project's output directory, alongside your main executable. This directory contains the debug database for GDB.

   • Note: Each time you recompile, a new debug database is created. If you manually copy your app, ensure you also copy this updated .DEBUG directory.

4. Install App on Device:

   • Install your debug-enabled app onto your jailbroken device using one of the methods described in Section 3.2.

5. Start Debugging Session:

   • Log in to your device as root via SSH.

   • Type the command: debugapp YourAppName (replace YourAppName with your app's name).

   • GDB will load and verify that your app and its debug database match. It will then wait for your app to start.

     iPhone-a-PM:~ root# debugapp Wolf3D
     ==============================================================================
     Please start Wolf3D manually on your device once GDB has loaded
     ==============================================================================
     Loading GDB...
     GNU gdb 6.3.50-20050815 (Apple version gdb-1708) (Fri Sep 16 07:00:41 UTC 2011)
     Copyright 2004 Free Software Foundation, Inc.
     GDB is free software, covered by the GNU General Public License, and you are
     welcome to change it and/or distribute copies of it under certain conditions.
     Type "show copying" to see the conditions.
     There is absolutely no warranty for GDB.  Type "show warranty" for details.
     This GDB was configured as "arm-apple-darwin"...Reading symbols for shared libraries . done
     
     Waiting for process 'Wolf3D' to launch.

   • Start your app on the device by tapping its icon on the SpringBoard.

   • The debugger will break in, load debug information, and await your commands.

     Attaching to program: `/private/var/mobile/Applications/6E86BB25-4866-402D-9C3E-8CF7D85753F3/Wolf3D.app/Wolf3D', process 30696.
     Reading symbols for shared libraries + done
     Reading symbols for shared libraries .............................................................................. done
     0x2fe6b796 in __dyld__ZN4dyldL10loadPhase5EPKcS1_RKNS_11LoadContextEPSt6vectorIS1_SaIS1_EE ()
     
     (gdb)

Common GDB Commands:

• break MyFunctionName or b MyFunctionName: Place a breakpoint at the beginning of MyFunctionName.

  • Example: (gdb) break Level_PrecacheTextures

• continue or c: Resume execution until the next breakpoint or until the program stops.

  • Example: (gdb) continue

• step or s: Single-step through your program, entering function calls.

  • Example: (gdb) step

• next or n: Single-step, but execute function calls without stepping into them.

• print MyVariableName or p MyVariableName: Display the current value of MyVariableName.

  • Example: (gdb) display leveldata.tilemap[x][y] (using display shows the value after each step)

• bt (backtrace): Display the call stack (the sequence of function calls that led to the current point).

• list or l: Show source code around the current execution point.

• quit or q: Exit GDB.

Example GDB interaction:

(gdb) break Level_PrecacheTextures Breakpoint 1 at 0x1ed68: file wolf\wolf_level.c, line 436. (gdb) continue Continuing. ... Breakpoint 1, Level_PrecacheTextures () at wolf\wolf_level.c:436 warning: Source file is more recent than executable. 436 for (x = 0; x < 64; x++) (gdb) step Current language: auto; currently minimal 437 for (y = 0; y < 64; y++) (gdb) step 440 if (leveldata.tilemap[x][y] & WALL_TILE) (gdb) display leveldata.tilemap[x][y] 1: leveldata.tilemap[x][y] = 1 (gdb)

For more comprehensive GDB tutorials, search online (e.g., "GDB tutorial"). The [GNU Debugger's official pro