GoLand 2023.3 Help

Examine suspended program

After the debugger session has started, the Debug tool window will appear, and the program will run normally until one of the following happens:

After that, the program is suspended, allowing you to examine its current state, control its further execution, and test various scenarios at runtime.

Examine frames

The state of the program is represented by frames. When the program is suspended, the current frame stack is displayed on the Frames tab of the Debug tool window.

Frames tab

A frame corresponds to the active method or function call. It stores the local variables of the called method or function, its arguments, and the code context that enables expression evaluation.

To better understand the concept of frames, let's look into what happens when a program is run. The execution of the program starts from the main method, which in turn calls other methods. Each of these methods may do more method calls. The set of local variables and parameters for each method call is represented by a frame. Each time a method is called, a new frame is added to the top of the stack. When the execution of a method is complete, the corresponding frame is removed from the stack (in the last in, first out fashion).

Examining frames helps you understand why particular parameters were passed to a method and what the state of the caller was at the time of calling.

Copy stack to clipboard

  • To copy the call stack for the current thread, right-click anywhere on the Frames tab and select Copy Stack.

Preview frames in one tab successively

The preview tab allows you to open files successively in one tab. This way you avoid cluttering the editor with multiple open files in separate tabs.

  • To enable the preview mode for files that are opened during debugging, open settings by pressing Control+Alt+S, navigate to Editor | General | Editor Tabs and select the Enable preview tab checkbox.

Hide object types

  • If object types take up too much space in the Debug tool window, right-click a variable and clear the Show Types option in the list that appears.

    debug-hide-object-types

Filter a list of goroutines in the dump tab

You can create a dump of all the goroutines that your program uses, apply a filter that searches for a specific goroutine, and study the filtered results. This procedure can help you to better understand how your program or its part works.

For example, the following screenshot shows the execution stack of the Goroutine 7 main.pageSize. A goroutine name in the list of goroutines is 'Goroutine <ID> <last_non-runtime_function_on_the_stack>. Non-runtime means that the function is not in the runtime package.

Execution stack of Goroutine 18 main.pageSize

Dump goroutines

  • During the debugging session, click More More and navigate to Dump Goroutines.

    A dump of available goroutines and their stacks opens in a separate tab.

    Dump goroutines

Filter the dump results

  • Click the Filter icon (the Filter icon). In the Filter field, type a string that you want to search for.

    Filter icon
  • Right-click a goroutine that you want to exclude from the list and select Hide goroutine. To hide all the goroutines that have the same stack as the selected goroutine, select Hide goroutines with the same stack from the context menu.

    You can view hidden goroutines under the Hidden list.

    To reset the state of the list and make all the hidden goroutines in the visible list again, click the Reset Hidden Goroutines button (the Reset Hidden Goroutines button).

    Hide goroutine

Export dump results into a text file

  1. Click the Export to Text File icon (the Export to Text File icon).

  2. In the Export to file field, select a storage path and click Save.

Export dump results into a text file

Examine/update variables

The Variables tab shows the list of the variables in the selected frame/thread. Examining the variables can help you understand why the program operates in a certain way.

The Variables tab shows you the variables visible from the current execution point

The icon on the left of each variable indicates its type.

Variable types

Icon

Description

Static members

Static members of the enclosing type

A field

Fields of an object (both static and nonstatic)

A field containing a self-reference

Fields containing a self-referencing object (for example, cause in Throwable before the field gets initialized)

A final field

Final fields

A static field

Static fields

A thrown exception

A thrown exception (only displayed when an exception breakpoint was hit)

A method return value

A method return value (only displayed when the Show Method Return Values option is enabled)

A parameter

Method parameters

An enum constant

Enum constants

An array

Local arrays

A primitive

Local primitive types

A watch

Watches and auto-variables.

A primitive

Local reference variables

Copy variables

When examining variables, you may need to copy a variable name or value to paste it somewhere else or to compare it with another variable.

  • To copy the name of a variable, right-click the variable and select Copy Name.

  • To copy the value that a variable holds, right-click the variable and select Copy Value Control+C.

Compare variables with clipboard

When you need to compare a variable value with some other value, use the Compare Value with Clipboard option. This is helpful, for example, when a variable holds a long string, and you need to compare it with another long string.

  1. Copy the content you want to compare (for example, from a text file).

  2. In the Variables tab, right-click the variable that you want to compare with and select Compare Value with Clipboard.

  3. Examine the differences in the Diff Viewer that opens. For more information about efficient using of the Diff Viewer, refer to the Comparing Files and Folders topic.

    RSA key in a text editor

View variables in a dedicated dialog

GoLand allows you to inspect variables in a dedicated dialog. This is useful when you need to keep track of some variable (or the object whose reference it holds) and at the same time be able to navigate between frames and goroutines.

  • Right-click a variable or a watch and select Inspect.

    Inspect dialog

Set variable values

If you want to test how the program would behave in certain conditions or fix its current behavior at runtime, you can do that by setting/changing the variable values.

  1. Select a variable and press F2. Alternatively, select Set Value from the context menu.

  2. Enter the value for the variable and press Enter.

If you need to look into the source code where some variable or type is declared, you can move there right from the Variables pane.

  • To navigate to the code where the variable is declared, right-click the variable and select Jump to Source F4.

    Jump to Source takes you to the place where the variable is declared
  • To navigate to the type declaration of the variable type, right-click the variable and select Jump to Type Source Shift+F4.

    Jump to Type Source takes you to the place where the type of the variable is defined

Evaluate expressions

GoLand lets you evaluate expressions during a debugging session to obtain additional details about the program state or test various scenarios at runtime.

Evaluate a simple expression in the editor

To quickly evaluate an expression, point at it in the editor. Note that method calls cannot be evaluated this way.

  1. Point at the expression you want to evaluate. The result of the expression appears in a tooltip.

    Value tooltip
  2. To view child elements of the resulting object, click the Expand button or press Control+F1.

    Resulting objects are represented by trees. This helps you view their internal state

If you find value tooltips distracting, you can increase the delay or disable them altogether. To do this, in the Settings dialog (Control+Alt+S), go to Build, Execution, Deployment | Debugger | Data Views and set the Show value tooltip and Value tooltip delay options as required.

Evaluate a complex expression in the editor

If you want to evaluate an expression in the code that involves a method call, or you want to be specific about which portion of expression to evaluate, use the Quick Evaluate Expression option.

  1. Place the caret at the expression (to evaluate the closest matching expression) or select a portion of it (if you want to be specific about which part of a complex expression to evaluate).

  2. Click Run | Debugging Actions | Quick Evaluate Expression Control+Alt+F8. Alternatively, hold Alt and click the selection.

    Value tooltip appears

You can configure Quick Evaluate to work for a piece of code on just selecting it (without using the menu/shortcut). Use this option carefully, as you can accidentally call methods when it is enabled.

To configure Quick Evaluate on code selection, go to Settings | Build, Execution, Deployment | Debugger | Data Views and set the Show value tooltip on code selection option as preferred.

Evaluate arbitrary expressions

Evaluating arbitrary expressions is the most flexible evaluating option. It lets you evaluate any code as long as it is in the context of the current frame. Using it, you can evaluate declarations, method calls, anonymous types, lambdas, loops, and so on.

Use this feature to get additional information about the current state of the program and test various scenarios all within the same debugging session. This saves a lot of time by reducing the number of sessions you have to run.

  1. If you want to start with some expression or a variable, which is currently in front of you (for example, in the editor or on the Variables pane), select it.

  2. Click Run | Debugging Actions | Evaluate Expression Alt+F8. The shortcut may not work on Ubuntu (for correct operation, adjust the shortcut configuration).

  3. In the Evaluate dialog, modify the selected expression or enter a new one in the Expression field. Click Expand Shift+Enter to modify a multiline code fragment.

  4. Click Evaluate (Control+Enter for multiline mode). The expression result appears in the Result field.

    The result of the expression is taken from the return statement. When there is no return statement, the result is taken from the last line of code (it does not even have to be an expression: a single literal works too). When there is no valid line to take the value from, the result is undefined. If the specified expression cannot be evaluated, the Result field indicates the reason.

    Expression result is calculated

The Evaluate dialog is non-modal, so you can switch the focus back to the editor to copy other variables and expressions. You can also open multiple Evaluate dialogs if necessary.

View values inline

GoLand shows the values of the variables right next to their usage.

Variable values are displayed at the lines where they are used

Once the variable value has changed, the inline view is updated with the new value and changes its color.

Inline values of the variables change with each step

The inline view is enabled by default. To turn it off, in the Settings dialog (Control+Alt+S), go to Build, Execution, Deployment | Debugger | Data Views and disable the Show values inline option.

Add an Inline Watch

If you want the result of some expression to appear on a particular line, you can set up an inline watch for that. Inline watches are persistent and remain active after session restart.

  1. Click the inline hint referring to the object whose field you want to track.

  2. In the popup, select the field and click Add as Inline Watch.

  3. Fine-tune the watch if needed. You can use any valid expression as a watch.

To remove an inline watch, hover over the watch and click the cross near it.

Watches

If you want to keep track of some variable or the result of a more complex expression, set up a watch for this variable or expression. This is useful when you need to evaluate something that is not regularly displayed on the list of variables, or to pin some instance variable thus eliminating the need to expand the tree after each step.

Watches are evaluated in the context of the selected frame. Watches cannot be evaluated when they are out of context or when they fail to compile. If this is the case, the watch is marked with the error icon Error icon.

By default, watches are shown together with variables in the Variables pane. To hide/reveal the Watches pane, use the Separate watches option in the Layout Settingsthe Restore Layout button menu.

Add a watch

  1. Click New Watch New Watch button on the Variables tab.

  2. Enter the variable or expression to be evaluated. In expressions, you can evaluate method calls, function literals declare variables, and so on, as long as this is in the local context.

    Watch expression

After you have added a variable/expression to Watches, it stays there and is evaluated for each step, providing you with the result in the current context.

Edit a watch

  • Right-click the desired watch and select Edit.

Copy a watch

  1. Select the watch you want to copy.

  2. Click Duplicate Watch Duplicate Watch button on the Variables/ Watches tab or press Control+D.

Change the order of watches

For convenience, you can change the order in which the watches appear on the Variables/ Watches pane.

  • Use the Move Watch Up/Move Watch Down buttons on the Variables/ Watches pane or Control+ArrowUp and Control+ArrowDown keyboard shortcuts.

Delete a watch

  • To remove a single watch, right-click it and select Remove Watch. Alternatively, select the watch and press Delete on the Variables/ Watches pane.

  • To remove all watches, right-click anywhere on the Variables/ Watches pane and select Remove All Watches.

Watches allow for the same actions as variables do. For example, you can view them in a dedicated dialog or use them to navigate to the source code.

Watches are a part of your project. This means you can stop and rerun the debugging session without risk of losing them.

Execution point

Return to the current execution point

Examining the program state involves navigating in code, and you often need to return to the place where your program is suspended.

Do one of the following:

  • In the main menu, go to Run | Debugging Actions | Show Execution Point.

  • Press Alt+F10.

  • Click The Show Execution Point button on the stepping toolbar of the Debug tool window.

The current execution point is indicated with a blue line. The code at this line has not been executed yet.

Blue line indicating the current execution point
Last modified: 11 January 2024