DebuggingMonoTouch applications can be debugged with the built-in debugger in MonoDevelop. To debug with MonoDevelop, you will need to install MonoTouch 1.2 and make sure that you are running the latest version of MonoDevelop. Use MonoDevelop's native debugging support for debugging C# and other managed languages code and use GDB when you need to debug C, C++ or Objective C code that you might be linking with your MonoTouch project. Using the MonoTouch/MonoDevelop debuggerIMPORTANT: when you compile applications in Debug mode, MonoTouch will generate slower and much larger applications as every line of code must be instrumented. Before releasing, make sure that you do a Release build. The MonoTouch debugger is integrated into MonoDevelop and it allows developers to debug MonoTouch applications built with any of the managed languages supported by MonoTouch in the simulator and on the device. The MonoTouch debugger is a soft-debugger, that means that the generated code and the Mono runtime cooperate with the MonoDevelop IDE to provide a debugging experience. This is different than hard debuggers like GDB or MDB which control a program without the knowlege or cooperation from the debugged program. You will start by setting breakpoints your application. This is done by clicking on the left hand side of your code or using the Command-/ key combination:
At that point, you can start your debugging session. Read the section below for important consideration about how to use the debugger on the device and on the simulator. Debugging on the SimulatorTo use the debugger, make sure that you have selected the iPhoneSimulator|Debug configuration option in MonoDevelop. When you do this, Mono will generate debugging symbols and MonoDevelop will activate the debugging mode on startup. To initiate a debugging session, start by setting breakpoints in the pieces of code that you want to debug (to trigger the debugger) and then start your application with Run/Debug either with Opttion-Command-Return, or from the menu:
Debugging on the Device.Debugging on the device using MonoTouch 4.0.4.1 or earlier requires you to have your iPhone or iPod Touch connected to the network. For MonoTouch 4.1 or later you must connect the device using the USB cable. Build Requirements: To use the debugger with the device, make sure that you have selected the iPhone|Debug configuration option in MonoDevelop (you can check this setting in the Project->Active Configuration menu):
Once you have selected this configuration option, you should Rebuild your solution (Command-Control-B, or Build->/Rebuild All). Important: Due to the requirements of the iPhone, the debug build of your code with MonoTouch will include the cooperative mono runtime and the code generated will be larger than a regular program as the generated code has been instrumented to be debugged. A debug build will be slower than a regular release build. Setting up your Network: [This step is only required for versions up to 4.0.4.1. Starting with MonoTouch 4.1 and MonoDevelop 2.6 beta 4 debugging is done over the USB cable.] You need to configure networking and your iPhone device should be able to reach your Mac. Either by configuring the WiFi in the iPhone and having your laptop on the same network or by having your Mac have a public IP address that the iPhone can reach through the build-in 3G or EDGE network support. This step is required because it is the application running on the iPhone that initiates the debugging by contacting the MonoDevelop IDE. Deploying and Debugging: To initiate debugging, you should upload your build to the device by selecting Run->Upload to Device. When the upload is done select Run->Debug from the menu and this will put MonoDevelop in debugging mode. Once the upload is complete, you will see this message:
At this point, you should manually launch the application on the device, it will connect to your MonoDevelop and initiate debugging. Breakpoints: It is important to point out that the iOS gives applications only a handful of seconds (10) to startup and complete the FinishedLaunching method in the Application delegate. If the application does not complete this method in 10 seconds, the OS will kill the process. This means that it is almost impossible to set breakpoints on the startup code of your program. If you want to debug your startup code, you should delay some of its initialization and put that into a timer-invoked method, or in some other form of callback method that is executed after FinishedLaunching has terminated. Device DiagnosticsFor MonoTouch releases before 4.1 (4.0.x and earlier), applications compiled with debug mode that has been deployed on the iPhone will try to contact MonoDevelop on startup on the IP address and port that MonoDevelop had at the time of the build. If there is an error setting up the debugger, the device will vibrate one or more times:
Additionally, when doing debug builds, MonoDevelop will modify the settings file for your project and insert a "Debug Settings" option. This is accessible from the iPhone Settings application and you can use this to enable or disable debugging at startup (for example, if you go out to dinner and want to show your application to some friends, but forgot to deploy a release version) or manually change the debugger host and port as well as the stdout/stderr port. Starting with MonoTouch 4.1, applications compiled with debug mode will listen for connections from MonoDevelop over the USB cable. If there is an error setting up the debugger, the device will vibrate one or more times:
In any case, detailed error information is also printed to the device console. Note that debugging over USB also requires an updated MonoDevelop (2.6 beta 4 or later), otherwise MonoTouch will behave as previous versions (debug over the network, see above). Technical Details.MonoTouch uses the new Mono soft debugger. Unlike the standard Mono debugger which is a program that controls a separate process by using operating system interfaces to control a separate process, the soft debugger works by having the Mono runtime expose the debugging functionality through a wire protocol. On startup, an application that is to be debugged contacts the debugger and the debugger starts to operate. This soft debugger requires a cooperative debugging scheme when running on the device. This means that your binary builds when debugging will be larger as the code is instrumented to contain extra code at every sequence point to support debugging. Accessing the ConsoleCrash logs and the output of the Console class will be sent to the iPhone console. You can access this console with XCode using the "Organizer" and selecting your device from the organizer. Alternatively, if you do not want to start up XCode, you can use the Apple's iPhone Configuration Utility to directly access the console. This has the added bonus that you can access the console logs from a Windows machine if you are debugging a problem in the field. Debugging Mono's Class LibrariesMonoTouch ships with the source code for Mono's class libraries, and you can use this to single step from the debugger to see how things are working under the covers. Since this feature consumes more memory during debugging, this is turned off by default. To enable this feature, make sure that the "Debug project code only; do not step into framework code" option in the MonoDevelop/Preferences/Debugger menu is turned off, like this
Once you do this, you can start your application and single step into any of Mono's core class libraries. You can see a video of this in action here: http://screencast.com/t/0FLUXkDk5ULU |
