How to use the Debugger, Introduction Tutorial

BlitzMax Forums/BlitzMax Tutorials/How to use the Debugger, Introduction Tutorial

col(Posted 2011) [#1]
I've noticed some new comers to the BlitzMax forums that don't realise that there is a debugger. So I've decided to write a little tutorial to help out our new friends.

This little tutorial is a simple introduction to the Debugger. It is by no means a comprehensive guide, merely an introduction to that fact that it exists and some information about the debugger controls, which will also include a little sample code that you can see working in the debugger.
Note - I'll be using the standard BlitzMax editor during the tutorial. There are other editors, but as this is aimed at new comers, I assume they'll also be using the standard editor that comes with the standard BlitzMax installation.

To use the debugger you need to make sure that 'Debug Build' is ticked. To do this – In the menus of the editor, go to 'Programs -> Build Options -> Debug Build.


I always use 'SuperStrict' in my code. My advice is to at least use 'Strict' or 'SuperStrict', this in itself can catch a LOT of errors before the code will even compile and run, such as duplicate definitions of variables or variables that aren't defined before use. It's also helpful in catching any typos that wouldn't normally get detected if you didn't use some kind of 'Strict'.

Ok, we're going to need some code to Debug.

In this example ( which doesn't contain errors ) we'll actually force the debugger to open during code execution using the 'DebugStop' command. The code simply creates an array called 'Array' with 20 integer elements. It then uses a simple loop to call a function that will assign each element of the array a value, and that value will be the same as the loop variable, which just so happens will also be the same value as its index position within the array. The reason for a function is purely to show how the debugger controls work.



So, before compiling and running this code, we'll need to know the debugger controls. They are the 4 icons in the toolbar above the code next to the 2 rocket ships in the above screenshot. The first rocket will just 'Build' the code( build an executable file) without running it. The rocket taking off is used to 'Build and Run' your code. This changes when the debugger is active to a green 'Continue' icon. Next to that is the 'Step' icon, ie step through your code one line at a time, but it will not step into any function calls although it will run the code in the function. The next is 'Step Into', this will step into a function call. Next is 'Step Out', this is used to step out of loops or step out of a function. The final one is the 'Stop' icon. It will stop code execution and return to the editor.


Let's set the above code in action to invoke the debugger. Click the 'Build and Run' icon or press 'F5'.


The code will stop execution at the first 'DebugStop' as shown above and notice the Debugger Control Icons have come 'alive'. Where the 'Build and Run' icon was is now a green 'Continue' icon. The current line ABOUT TO BE executed is highlighted in blue in the source code, this line of code hasn’t been executed yet. If you pressed the green 'Continue' icon then the program will carry executing as if the 'DebugStop' command never existed. In the example code it will run the code and stop again at the second 'DebugStop' command. If you select 'Continue' again the program will simple finish.

Ok, if you Build and Run again so that the debugger opens at the first 'DebugStop', notice the right hand pane has some details about the variables in this code. I'm not sure why but the main program is referred to as a 'Function' in the debugger variables. Expand the 'Function' using the plus sign to show the Array, then click the plus sign next to that to show the contents of the array. The debugger will usually show ten elements at a time, so click the plus sign under element 9 to expand the next ten elements too, as shown below.


You can also see the memory address next to the Array:Int[] definition. This can also help when you are doing some advanced coding using pointers etc, but that beyond the intention of the introductory tutorial.

If you click the 'Step' icon, the next line to be run will be the For..Next line. 'Step' again to start the loop and you'll see that the 'iterator' variable is now added to the variables list in the right hand pane. This is because it's a 'Local' variable, local only to the loop. Using 'Step' again you can see the iterator variable counting up from 0 to 19 and also take note that the arrays element values are changing too. Also note that because we are using the 'Step' icon, the debugger doesn't 'step into' the source of the 'UpdateArray' function, but you can clearly see it must be getting executed or the contents of the array wouldn’t change.
If you press the 'Step In' icon then the debugger will step into the source of the 'UpdateArray' function and also add the 'Function UpdateArray' to the variable list in the right pane. Clicking the plus sign next to 'Function UpdateArray' will show the value of the 'Element' variable that's being passed in too. If there were more variables inside the function then they would get listed also.

If you are debugging inside a function and you use 'Step Out' icon then you will step out of that function. Again all of the code is executed as normal before leaving the function.
If you use 'Step Out' while inside a loop, the loop will be completely executed as normal before leaving that loop and stopping at the next instruction after it.

NOTE - If you keep 'stepping in' through the source, you will actually step through the source code of BlitzMax language itself ( inside the module code ). Yep, BlitzMax is used to write the BlitzMax language ;-)

This next example will show how to invoke the debugger when you have an error in your code. A seasoned BlitzMax programmer will spot the mistake immediately, but to a beginner it may not be so obvious.



Build and Run the above code. Notice that it will compile and run. Everything looks ok but you get...


If you didn't have the 'Debug Build' option ticked, you will probably get an 'Exception Access Violation' window leaving you clueless as to the problem. ( EDIT:- Actually you don't using this very simple example :/ I assume because of compiler optimisations?? but it does compile and work fine outside of 'Debug Build' mode. In a more complicated program like a typcial game then you would get an EAV )

Because 'Debug Build' is selected and you now have an error, it has invoked the debugger automatically for you. Close the error notification window and you are returned to the editor highlighting the line of source code that has caused the error. Remember this MAY NOT actually be the line of code that is at fault! It merely means something is wrong when trying to run this line of code.
At this point there's not more you can do except look through the source code, look though the variables in the right hand pane or 'Stop' the debugger ( and code execution ) to return to the editor. You can't step through the source like you can when you use the 'DebugStop' command.

We want to find the problem so... looking at the variables on the right hand pane, click the plus sign to open the 'Function UpdateArray' variables. It shows variable 'Local Element:int=0'. This looks normal and as expected, so let's look at the Array itself, after all it is being used here inside the 'UpdateArray' function. Open the topmost 'Function', which is preceded with the name of the source file, then open the 'Array:TestType[]'.


You'll notice that the array is full of 'Null' elements and this is the cause of the problem. We are trying to access the Array elements, 'Array[ Element ] = Element', but it doesn't actually exist just yet. This is because all 'Type's need to be 'New'ed before you can use them. Take a look at the code below and notice the first line inside the 'iterator' loop.



The array elements are Types which need to be created before being used, hence the 'Null' elements in the array and also the 'accessing a Null object' in the error window.
Place a 'DebugStop' just after the 'Global Array:TestType[20]' and Build and Run the code again. Using the 'Step' or 'Step Into' button you can watch the variables being created in Array[] in the right hand pane.

You can use the debugger to look at all the Global variables in your code at any time, but you can only look at any 'Local' variables when they are being used. You can also look inside instanced Types to see the 'Field' values, including if a 'Field' is a Type variable too, then you can look at its Field variables as well.


Have fun.

Last edited 2011


wongojack(Posted 2014) [#2]
Bumping an old post because this really helped me. I'm also going to add the phrase BreakPoint here because that is how I think about this functionality. DebugStop is similar to a Break Point.


GfK(Posted 2014) [#3]
I'm also going to add the phrase BreakPoint here because that is how I think about this functionality. DebugStop is similar to a Break Point.
It's not similar to a breakpoint, it IS a breakpoint.


wongojack(Posted 2014) [#4]
It's not similar to a breakpoint, it IS a breakpoint.


:)

Good to know I was on the right track. Hopefully adding that phrase here will help with others searching the forums for how to set a breakpoint.


Who was John Galt?(Posted 2014) [#5]
Missed this one first time around- it's a good tute.