Legacy Documentation: Version 5.1
Console
Attaching MonoDevelop Debugger To An Android Device

MonoDevelop

MonoDevelop is the integrated development environment (IDE) supplied with Unity. An IDE combines the familiar operation of a text editor with additional features for debugging and other project management tasks. The text editor will not be covered here since it is fairly intuitive, but the integration of the editor and debugger with Unity are described below.

Setting Up MonoDevelop

MonoDevelop is installed by default with Unity, although there is the option to exclude it from the installation on Windows. You should check that MonoDevelop is set as the external script editor in the Preferences (menu: Unity > Preferences and then select the External Tools panel). With this option enabled, Unity will launch MonoDevelop and use it as the default editor for all script files.

Setting Up the Debugger

To enable MonoDevelop’s source level debugging (see below for details) you should firstly check that the Editor Attaching option is enabled in the Preferences on the External Tools panel. Then, you should synchronize the Unity project with the MonoDevelop project (menu: Assets > Sync MonoDevelop Project). Also, make sure that the Development Build and Script Debugging options are enabled in the Build Settings for your target platform (menu: File > Build Settings). If you are building a webplayer then you should additionally check that the development release channel setting is enabled on the player’s context menu in the browser (right click on Windows or cmd-click on Mac OSX).

Enabling debugging in the webplayer
Enabling debugging in the webplayer

Just before starting a debugging session, select Run > Attach To Process from the menu in MonoDevelop and then select the Unity application from the list of processes that appears. With these steps completed, you are ready to being debugging your Unity scripts.

Source Level debugging

The currently open source files are shown as tabs in MonoDevelop and can be edited there with the features of a standard text editor. However, there is also a grey breakpoint bar to the left of the editor panel. Clicking in this bar will add a so-called breakpoint marker next to the line of code.

Breakpoint being added to code on line 16
Breakpoint being added to code on line 16

Adding a breakpoint to a line instructs Unity to pause execution of the script just before it reaches that line during Play mode. When the script is “frozen” like this, you can use the debugger to determine exactly what the script is doing.

The arrow shows execution paused at the breakpoint
The arrow shows execution paused at the breakpoint

Information about the state of execution is shown in the tabs at the bottom of the MonoDevelop window when execution is paused at a breakpoint. Perhaps the most important of these is the Locals tab.

Tab showing variable values
Tab showing variable values

This shows the values of local variables in the function that is currently executing. (A pseudo-local variable called “this” is automatically available in every function without being explicitly defined; it is a reference to the current script instance and so all variables defined in the script can be accessed via “this”.) You can use breakpoints in combination with the Locals tab to get a similar effect to adding print statements to your code - you can interrogate the values of variables at any point you like. However, you can also edit the variable values in the Locals tab. This can be handy when you find a variable incorrectly set and you would like to see if the problem disappears when the value is set how it should be.

A further useful feature of MonoDevelop is single stepping. When execution is paused at a breakpoint, a bar of debugging tools will become available in the top portion of the MonoDevelop window:-

MonoDevelop stepping tools
MonoDevelop stepping tools

The first four buttons are known as Continue, Step Over, Step In and Step Out and can also be accessed as commands on the Run menu (the rightmost button, Detach, can be used if you want to end the debugging session). Continue resumes execution until the next breakpoint is encountered. Step Over and Step In both execute one line of code at a time. The difference between the two is that Step Over executes any function calls within the line all at once, while Step In allows the stepwise execution to continue into the function. Since it is common to use Step In accidentally on a function that is known to be correct, Step Out continues execution to the end of the current function and then pauses again in the code that originally called it.

A detailed description of source level debugging techniques is not appropriate here but there are various books and web resources offering wisdom on the subject. Additionally, a little experimentation will help you get a feel for the power of the technique and how you can use it to track down most common types of bugs.

Console
Attaching MonoDevelop Debugger To An Android Device