Atlas includes a fully functioning debugger for you to run your code, line by line. In this section we will dive into all the functionality that is included with our debugger. To open the Debug View, click this icon:
Basic Debugging Operations
All the basic and expected debugging operations are supported with the Atlas debugger. See below for a detailed description of each one of them.
To start a debugging session you can select Start Debugging from the Debug menu, press the F5 hotkey, or click this button from the Debug View. This will initialize the debug session and allow you to interrupt execution to look at variables, double check operation, or track down problems in the model code.
To pause the execution of the current model debug session, select the Pause option from the Debug menu, press the F6 hotkey, or press this button from the Debug View. If the execution of your model is taking a long time and it is unclear why, this will pause execution exactly where it is and allow you to see what might be causing your model to take so long to run.
Once you have concluded your work in a paused state, or to continue from a breakpoint, you can resume execution by selecting the Continue option from the Debug Menu, pressing the F5 hotkey, or pressing this button.
If, for any reason, you need to stop execution completely, you can select the Stop Debugging option from the Debug Menu, press the Shift+F5 hotkey, or press this button.
While in a running debug session, if you need to restart debugging from a fresh state you can select the Restart Debugging option from the Debug Menu, press the Ctrl+Shift+F5 hotkey, or press this button from the Debug View.
When you have paused execution, particularly when you have hit a breakpoint in your model code, you can continue execution in a line by line manner. To do this you can select the Step Over option in the Debug Menu, press the F10 hotkey, or press this button from the Debug View. When you select this action and the line of code contains a function call, this will STEP OVER the function call itself to the next line of code.
If you are executing code in a line by line manner and you want to step into function calls that you encounter, you must STEP INTO them. To do this you can select the Step Into option in the Debug Menu, press the F11 hotkey, or press this button from the Debug View.
If you are executing code in a line by line manner and have stepped into a function you will find that continuing execution by using the Step Over option can take a while and many button presses. You can finish the execution of the current function and break immediately after it by using the STEP OUT option. You can do this by selecting the Step Out option from the Debug Menu, pressing the Shift+F11 hotkey, or pressing this button from the Debug View.
There are a number of ways that you can stop execution outside of pressing Pause while debugging. The various breakpoints are detailed below.
To set a standard breakpoint simply click in the left-most margin on the editor tab for the file you want to debug, on the line that you want to stop execution. You can also set your cursor to the line you want to break on and select the Toggle Breakpoint option from the Debug Menu, or simply press the F9 hotkey. The breakpoint will be set successfully if you see a solid red dot that persists at that line after you move your mouse. The model code execution will not stop when it reaches this line.
An inline breakpoint will stop execution not only on a particular line, but also at a particular spot in the statement on that line. A single line of code can contain many items that need to be executed. If you want to specify which one on that line to stop execution on, you can set an inline breakpoint by setting your cursor to the part of the line you want to break on and selecting the Inline Breakpoint option from the Debug Menu under the New Breakpoint sub-menu, or simply pressing the Shift+F9 hotkey. An inline breakpoint looks like this.
Conditional breakpoints are when you only want to stop execution if a certain condition is met, say, when you want to pause during a for-loop execution on the 5th element. To do this, set your cursor to the line you want to stop execution on and select the Add Conditional Breakpoint… option from the Debug Menu New Breakpoint sub-menu. This will bring up an area for you to enter the conditional expression you want to be met for the breakpoint to be hit.
A conditional breakpoint looks like this.
Function breakpoints allow you to set breakpoints without opening up your model and finding the exact line to set a breakpoint on. If you know the name of the function, then you can add a function break point to always pause execution at that function. To add a function breakpoint, select the Add Function Breakpoint… option from the New Breakpoint sub-menu in the Debug Menu. This will bring up a dialog where you can enter the name of the function you want to break at. This will add another entry to the breakpoints section that looks like this.
A breakpoint that is not a breakpoint is a logpoint. Logpoints are valuable when you want to include logging while debugging, but not actually in your code. When a logpoint is reached, execution doesn’t stop. Instead a log message is output to the console. To create a logpoint, set your cursor to the line and position that you want the log message to occur. Select the Add Logpoint option from the New Breakpoint sub-menu of the Debug Menu. Enter a message that you want to log when this point is reached and hit Enter to accept. The new logpoint will show up in the editor and in the Breakpoints section and will look like this.
Debug View Sections
The different sections of the Debug View will show you important information about the runtime nature of your code. There are some sections that contain information across many files, like Threads contains all running threads across all files and Breakpoints contains all breakpoints set in all files.
The Threads section of the Debug View will show you all of the threads that you have running, across all of your models. Clicking on any of the entries in this list will take you to the file that it is linked to, if not already active in the editor.
The Call Stack section of the Debug View will show you the execution call stack of the selected thread. For more complicated models that call into various functions this can be invaluable when tracking down issues in your model code.
The Variables section of the Debug View will show you all local variables within the context of your debug session. This is extremely valuable when you want to look at the value of any of your model objects while the debugger is paused. You can even set a variable value manually, while paused, if there are certain conditions that you want to check. To do this simply select the Set Value option from the right-click context menu and enter the value you want.
While the Variables section is limited to local variables, the Watch section allows you to focus on both variables and expressions. To add an entry to the watch list click on the plus icon in the section’s header. This will give you an input box where you can type the name of the variable or the expression that you want to watch. Once entered, the variable or expression will show up in the watch list and update as appropriate during your debug session.
The Breakpoints section of the Debug View houses the info for all the breakpoints that have been set across all files in the workspace. Double clicking on any one of them will open the file that contains the breakpoint, or set it as the focus in the editor, as well as showing the line of the breakpoint. You can also enable or disable the breakpoints by checking or unchecking the boxes, as well as delete them from this list.
Peeking in Objects
While an active debug session is paused you are able to peek at the value of a variable by hovering over it in the editor. The resulting popup will allow you to browse the properties and members of the object and peek at their values.
Setting Debug Configurations
This is a very advanced action to take, but if you are familiar with VSCode-like debug configurations you can add them by editing the launch.json file. To do so select Add Configuration… from the drop down in the Debug View. For nearly all cases, it is best to stick with the default configuration we provide.
The debug console is where all output from an active debug session will be printed. Keep in mind that since many active sessions can be going on at once (you can debug many models at once) the debug output will all go to the debug console. If you accidentally close it, you can open it again by pressing this button.