Skip to content

Debugging in VS Code#

Jac integrates with VS Code's debugging infrastructure through the Jac extension, giving you the same debugging experience you'd expect from Python or JavaScript: breakpoints, step-through execution, variable inspection, call stacks, and watch expressions. The extension also includes jacvis, a live graph visualization tool that renders your graph structure in real time as you step through walker traversals -- so you can see nodes and edges appear as your code builds the graph.

This tutorial walks you through setting up the debugger, using breakpoints effectively, and visualizing graph operations during debugging sessions.

Prerequisites

  • Python 3.12+
  • jaclang installed
  • VS Code with Jac extension
  • Time: ~15 minutes

Quick Start#

If you're already familiar with debuggers:

  1. Install Python 3.12+ and jaclang
  2. Install VS Code + Jac extension
  3. Create launch.json (Debug and Run > Create launch.json > Jac Debug)
  4. Open VS Code Command Palette and run jacvis for graph visualization
  5. Set a breakpoint > Run Debugger > Inspect variables

What is the Jac Debugger?#

The Jac Debugger helps you find and fix issues in Jac programs. It supports:

  • Breakpoints - Pause execution at specific lines
  • Step-through execution - Execute code line by line
  • Variable inspection - View local and global variable values
  • Graph visualization - Unique to Jac: see your nodes and edges visually

One-Time Setup#

Complete these steps once per computer.

Requirements#

Requirement How to Check
Python 3.12+ python --version
jaclang jac --version
VS Code Download
Jac Extension Extensions tab > search "Jac"

Enable Breakpoints in VS Code#

To set breakpoints in Jac files:

  1. Open VS Code Settings
  2. Search for "breakpoints"
  3. Enable Debug: Allow Breakpoints Everywhere

Install Jac Extension#

  1. Open VS Code Extensions panel
  2. Search for "Jac"
  3. Click Install

Project Setup#

Do this for each new Jac project.

Create launch.json#

launch.json tells VS Code how to run the debugger.

  1. Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
  2. Click Create a launch.json file
  3. Select Jac Debug
  4. VS Code generates the configuration automatically

Your .vscode/launch.json will look like:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "jac",
            "request": "launch",
            "name": "Jac Debug",
            "program": "${file}"
        }
    ]
}

Using Breakpoints#

Breakpoints pause execution so you can inspect program state.

Setting a Breakpoint#

Click in the gutter (left of the line number) to set a breakpoint:

def complex_calculation(x: int, y: int) -> int {
    result = x * 2;          # <- Set breakpoint here
    result = result + y;
    result = result ** 2;
    return result;
}

with entry {
    answer = complex_calculation(5, 3);
    print(answer);
}

Running the Debugger#

  1. Set your breakpoint
  2. Press F5 or click Run and Debug
  3. The program pauses at the breakpoint

Debugger Controls#

Action Shortcut Description
Continue F5 Run until next breakpoint
Step Over F10 Execute line, skip into functions
Step Into F11 Execute line, enter functions
Step Out Shift+F11 Run until current function returns
Restart Ctrl+Shift+F5 Restart from beginning
Stop Shift+F5 Stop debugging

Inspecting Variables#

When paused, the Variables panel shows:

  • Local Variables - Variables in the current function scope
  • Global Variables - Variables defined at module level

Graph Visualization#

Jac's debugger includes a visual tool to see your graph structure in real time.

Example Graph Program#

node Person {
    has age: int;
}

with entry {
    # Create people nodes
    jonah = Person(16);
    sally = Person(17);
    teacher = Person(42);
    jonah_mom = Person(45);

    # Connect Jonah to root
    root ++> jonah;

    # Create Jonah's relationships
    jonah ++> jonah_mom;
    jonah ++> teacher;
    jonah ++> sally;
}

Opening the Graph Visualizer#

  1. Open the VS Code Command Palette:
    • Windows/Linux: Ctrl+Shift+P
    • macOS: Cmd+Shift+P
  2. Type jacvis
  3. Select jacvis: Visualize Jaclang Graph

A side panel opens showing your graph.

Watching the Graph Build#

  1. Open the graph visualizer panel
  2. Set a breakpoint in your code
  3. Start debugging (F5)
  4. Step through the code - watch nodes and edges appear in real time

You can drag nodes around to better visualize the structure.

Troubleshooting#

Problem Solution
Breakpoints are grey / don't trigger Enable Debug: Allow Breakpoints Everywhere in VS Code settings
"No Jac debugger found" Reload VS Code window after installing Jac extension
Program runs but debugger doesn't stop Use Run and Debug (F5), not the terminal
Graph doesn't update Open jacvis before starting the debugger

Next Steps#