14.2 Setting Breakpoints and Stepping Through Code

Why Breakpoints Matter

When you debug MATLAB code, you usually want the program to pause at a specific line so you can see what is happening. A breakpoint is a marker you place in a file to tell MATLAB to stop just before executing that line. Once the program is paused, you can run the code one step at a time, inspect variables, and understand how the code is behaving.

Using breakpoints and stepping is the main interactive way to debug scripts and functions. They only affect code that runs from files, not commands you type directly in the Command Window.

Placing Breakpoints in the Editor

You usually set breakpoints in the MATLAB Editor, where your script and function files are open.

To set a basic breakpoint, click in the narrow grey margin to the left of a line of code. MATLAB shows a red circle next to the line number. This line is now a breakpoint. When you run the file, MATLAB will pause just before it runs that line.

You can toggle that breakpoint on and off by clicking the red circle again. If you turn it off, the circle disappears and the code will no longer stop at that line.

Only executable lines can have a breakpoint. For example, blank lines and comment-only lines cannot hold a breakpoint. If you click next to a comment line, MATLAB usually moves the breakpoint to the next executable line in that block.

You can also use the Editor toolbar. There is a button that adds or removes a breakpoint at the current cursor line. This is helpful when you work mainly with the keyboard and do not want to move the mouse to the margin.

Using the Current Line Indicator

When the code is running and hits a breakpoint, it enters a paused state, often called debug mode. In the Editor, MATLAB highlights the line about to be executed, usually with a different background color and a green arrow in the margin.

This highlighted line is called the current line. In debug mode, MATLAB did not execute this line yet. It will be the next line to run when you continue or step. The current line indicator helps you understand exactly where you are in the code.

The Command Window prompt also changes when the code is paused, so you can tell that MATLAB is not at the usual idle state.

Starting Execution and Hitting Breakpoints

To use breakpoints effectively, you need to start your code in a way that reaches them.

If you are debugging a script, you can usually run it by pressing the Run button in the Editor or by typing the script name in the Command Window. If you are debugging a function, you can call it in the normal way. For example, if the function file starts with

function y = myfun(x)

you would type:

y = myfun(10);

If MATLAB reaches a line with a breakpoint in that file, it stops there and switches into debug mode. Everything after that line waits until you step or continue.

If the code never reaches that line, for example because of an if condition that is false, the breakpoint will not trigger. In that case you need to adjust your test inputs or move the breakpoint to a line that is always reached.

Stepping Through Code: Step, Step In, and Step Out

Once the code is paused at a breakpoint, you can move forward through the code in small pieces. The Editor provides three main stepping actions. You can access them from the toolbar buttons or with keyboard shortcuts.

Step executes the current line and then pauses at the next executable line in the same file. If the current line calls another function, Step treats that call as a single unit and does not enter that function. This is useful when you trust the called function and want to debug only the current file.

Step In executes the current line and, if it calls a function, enters that function and pauses at the first line inside it. This lets you follow the flow into nested function calls and see what happens inside them. If the current line does not call another function, Step and Step In behave the same for that line.

Step Out runs the rest of the current function without stopping and then pauses on the line that called this function. This is useful when you have gone too deep into nested calls or you finished checking something in a function and want to return to the caller without stopping at every line.

When using these actions, watch how the current line indicator jumps. This visual feedback shows you which line is next and whether you are inside a different function file or back in a script.

Continuing Execution after a Breakpoint

Sometimes you do not want to step line by line, but instead run until the next breakpoint or until the code finishes. In that case, use Continue.

Continue executes from the current line and runs at full speed until one of these happens. MATLAB reaches another breakpoint in any file. An error occurs. The program finishes.

If you have multiple breakpoints in different functions or scripts, Continue lets you move from one breakpoint to the next without manually stepping through all the lines in between.

If the code finishes without hitting another breakpoint, MATLAB leaves debug mode and returns to the normal Command Window prompt.

Setting Conditional Breakpoints

A conditional breakpoint stops only when a certain condition is true. This is useful when you are debugging loops or repeated function calls and you want to pause only in specific cases, for example when a variable exceeds a value or when an index equals a certain number.

To set a condition in the Editor, right click the red breakpoint circle and choose the option to set a conditional breakpoint. MATLAB opens a small box where you can type a logical expression. This expression is evaluated in the workspace of the file when that line is reached.

For example, if you are inside a loop with a variable k, you might set the condition

k == 10

Then MATLAB will run the loop without stopping until k equals 10 at that line. Another example is

errorFlag ~= 0

which would cause a stop only when errorFlag is not zero.

The expression should be something MATLAB can evaluate to a logical true or false. If the expression itself has an error, MATLAB may not be able to reach the breakpoint correctly.

When a breakpoint has a condition, its icon in the margin looks slightly different so you can distinguish it from a normal breakpoint.

Temporarily Disabling Breakpoints

During a debugging session, you may want to keep some breakpoints defined but not active for a while. MATLAB lets you disable a breakpoint without deleting it.

To disable a single breakpoint, right click its icon in the margin and choose the disable option. The icon usually becomes hollow or grey, which indicates that it is present but inactive. MATLAB will ignore it when running.

You can enable it again later using the same menu. The icon returns to the solid red look when it is active.

You can also use the Editor tools to clear or disable all breakpoints in the current file, or even in all open files. This is useful if you finished a debugging session and want to run the code normally without hitting old breakpoints, but you may still want to keep them in mind for later and re enable them if needed.

Managing Breakpoints across Files

When your project has several scripts and functions, breakpoints can be placed across many files. MATLAB provides ways to see and manage all of them.

In the Editor, you can usually open a Breakpoints list or use menu options to jump from one breakpoint to the next within a file. Some versions also provide a report of all breakpoints across open files. You can use this to check whether you left a breakpoint somewhere that might interrupt future runs.

Breakpoints only apply to the exact file and line where they are set. If you rename a file or copy code to a new file, those breakpoints do not move automatically. If you change the code so that lines are added or removed above a breakpoint, MATLAB keeps the breakpoint attached to the same logical line in most cases, but it is good practice to glance at the margin after a big edit and verify that breakpoints are still where you expect.

Using Command-Line Debugging Commands

Although the Editor is the main place to work with breakpoints, MATLAB also provides command line functions that control debugging. These are helpful when you work on a system without the full graphical interface or when you want to automate some debugging setup.

To set a breakpoint from the Command Window, you can use dbstop. For example:

dbstop in myfile at 15

sets a breakpoint at line 15 in myfile.m. You can also set breakpoints that stop on errors or warnings, for example

dbstop if error

which tells MATLAB to enter debug mode at the line that causes an error, even if you did not set a breakpoint in advance.

To continue from a paused state, you can type dbcont in the Command Window. To step, you can use dbstep. For example, dbstep without arguments steps once, dbstep in steps into a function, and dbstep out steps out. These do the same as the Step buttons in the Editor.

To remove breakpoints from the command line, you can use dbclear. For instance:

dbclear in myfile

removes all breakpoints in myfile.m. The command

dbstatus

shows you a list of all current breakpoints and debug settings, which is useful to review before running code.

Exiting Debug Mode Cleanly

When you are done debugging, you should leave debug mode so MATLAB returns to normal operation. If the code is paused at a breakpoint, you can either let it finish by using Continue, or you can abort its execution.

To abort, press the Stop button in the Editor or click the red square in the toolbar, depending on your MATLAB version. From the Command Window, you can usually press Ctrl+C to interrupt execution. MATLAB then stops the running code and exits debug mode.

If you used dbstop if error, MATLAB will keep that rule active until you remove it or end the session. You can clear it with:

dbclear if error

This prevents MATLAB from unexpectedly entering debug mode on future errors when you just want to see the message.

Before you finish, consider disabling or removing breakpoints that you no longer need. This avoids confusion when you run the same script or function later and it pauses unexpectedly.