Juliet & Romeo VS Code Extension

The Juliet & Romeo VS Code extension provides support for Juliet by connecting VS Code to the language server/debug adapter (devenv) running locally or on a reachable host; devenv in turn connects to the Romeo Virtual Machine (RVM). Configure the target host/ports and ensure devenv is running to unlock language services and debugging. For setup help, see Installing RVM and Devenv (local) or Connecting to a Remote Host (remote target).

Features

Language Support

Highlights core Juliet syntax and provides hover details, go to definition, and diagnostics where available.

Debug Support

• Run or debug the active file from the editor title bar run/debug icons.
• Use Jump to Cursor from the editor context menu (right-click in the editor) to move the instruction pointer to the selected line without running intervening code.
• Use Run to Cursor from the editor context menu (right-click in the editor) to continue execution until the selected line.
• Breakpoints (regular) and stepping controls: continue, pause, step over/into/out/back and continue step.
• Call stack view.
• Locals/globals in VARIABLES watch when a debug session is active.
• Continuous Watch for globals.
• Multitask awareness: commands operate on the selected task in CALL STACK.

Continue Step

• The Continue Step button is always visible in the Juliet debug toolbar but is only enabled when execution is stopped during a step, either with pause or breakpoint.
• When enabled, it continues the previous step command from that stop.

Resetting Task Errors

• When a task stops on an exception, right-click that task in the CALL STACK and choose Juliet: Reset task error to clear the error.
• The command is available on thread entries whenever the debug session is stopped; if the selected thread is not currently paused on an exception you'll see Cannot reset task error: thread is not in an exception state.

Stop-State Edit

• Edit code while paused and click the status bar prompt (Apply edits…) to reload changes into the running debug session.
• All tasks must be paused for an apply to succeed; with multiple tasks, pause them all first. Pause tasks from the CALL STACK view (or its hover controls) in the debug sidebar.
• Toggle Auto pause/apply/resume from the editor context menu (right-click in the editor) or the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) to let the extension pause tasks, apply the change, and resume automatically; this safety toggle resets at the end of each debug session.

Warning, use with caution: Auto pause/apply/resume will pause all running tasks and automatically start them with new applied code. Only use it when it is safe to stop and resume a running task and make sure the new code is correct before applying.

• The debug console reports whether the apply succeeded or failed.

Installation

Installing RVM and Devenv

The extension requires RVM and Devenv to enable debugging and runtime features. You can install these from the VS Code extension:

Note: RVM and Devenv can only be installed on Linux-based systems. Windows and macOS users can connect to a remote Linux host running RVM/Devenv (see Connecting to a Remote Host).

Using the Status Bar

1. Look for RVM and Devenv indicators in the status bar (bottom right)
2. If binaries are missing, they will show as RVM (missing) / Devenv (missing)
3. Click on the missing indicator
4. Select "Install jlt-rvm package" from the menu
5. Choose your package file:
   • Debian/Ubuntu: Select .deb package (requires dpkg-deb)
   • Other distributions: Select .snap package (requires squashfs-tools)
6. The extension will validate and install the package automatically

Package Requirements

• Architecture: Must match your system (amd64 or arm64)
• Debian packages (.deb):
  • Supported on Ubuntu and Debian systems
  • Package name: jlt-rvm
• Snap packages (.snap):
  • Supported on all Linux distributions
  • Package name: ctrlx-cognibotics-juliet-romeo
  • Format: ctrlx-cognibotics-juliet-romeo_<version>_<arch>.snap
  • Requires squashfs-tools (the extension will help with installation it if missing)

Post-Installation

After successful installation:

• RVM and Devenv will start automatically (if Devenv host is set to localhost)
• Status bar indicators will update to show running state
• You can now debug and run Juliet programs

Managing Processes

Click on the RVM or Devenv status bar items to:

• Start/Stop processes - Control owned processes
• Restart processes - Restart owned processes
• Restart in terminal - View process output in visible terminal
• Take ownership - Kill external processes and start new owned instances (shown when process is marked as "external"); if the external processes run under different permissions, the extension must have matching permissions or it will show an error
• Install jlt-rvm package - Install binaries when marked as "missing"
• Set Juliet load path - Configure package paths (for devenv); requires rvm and devenv to be owned by the extension (not marked external)

Connected to remote host: Workspace Structure

The extension expects a specific workspace structure for proper dependency resolution when connected to a remote host.

Package Layout

All packages must be at the same directory level (siblings) within the workspace. The extension scans for top-level packages and resolves dependencies between them automatically.

Example structure:

workspace/
├── MainProject/
│   ├── Project.toml
│   └── src/
│       └── MainProject.jlt
├── PackageA/
│   ├── Project.toml
│   └── src/
│       └── PackageA.jlt
└── PackageB/
    ├── Project.toml
    └── src/
        └── PackageB.jlt

Project.toml Requirements

Each package must have a valid Project.toml file with:

1. Package name - Required for dependency resolution:

   name = "PackageA"
   

2. Dependencies - If the Package has any dependencies (like MainPackage in this example has), declare them under the [deps] section:

   [deps]
   PackageA = ""
   PackageB = ""
   

The extension automatically:

• Detects packages with a main() function
• Resolves dependencies
• Sends the complete dependency closure to the language server
• Updates when Project.toml files change

Known Limitations

• Only single-root workspaces with flat package structure are handled correctly
• Dependencies must exist as top-level packages in the workspace - external or nested packages will not be resolved

Connecting to a Remote Host

By default, the extension manages local RVM and Devenv processes on localhost. To connect to Devenv running on a different host:

Configuration

Configure the remote host using either method:

Method 1: Command Palette (Workspace level only)

1. Open Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
2. Run command: Juliet: Change target host and port
3. Enter the connection details when prompted

Method 2: Settings UI

1. Open VS Code Settings (File > Preferences > Settings or Ctrl+,)
2. Search for juliet.devenv settings
3. Configure connection type and connection parameters (see Settings Table for all options)
4. Configure at User level (all workspaces) or Workspace level (current project only)

Behavior with Remote Host

When configured to use a remote host:

• The extension will not start or manage RVM and Devenv processes locally
• You are responsible for starting and managing RVM and Devenv on the remote host

Port Configuration

If the remote Devenv uses non-default ports, configure:

• juliet.devenv.dap.port - Port for Debug Adapter Protocol (default: 1234)
• juliet.devenv.lsp.port - Port for Language Server Protocol (default: 1235)

Target Auto-Discovery

• On startup the extension scans the local network (Bonjour/mDNS) for discoverable Juliet targets. Results are cached and retried once if nothing answers.
• Currently discovered target types: Bosch Rexroth ctrlX and KEBA devices.
• A new status bar item (radio tower icon) shows the active host/port, LSP connection state, and how many targets were discovered; hover to see the list.
• Click the status bar to the lower left to open the discovery Quick Pick: discovered targets carry a broadcast icon, saved/manual ones show a star, and localhost is always available.
• Quick Pick actions: Rescan network…, Save current target (adds to juliet.devenv.savedTargets), Remove saved target…, and Change host/port… (opens the manual host/port prompts).
• Picking a target updates workspace settings and restarts the Juliet client with the right defaults (ctrlX targets switch to TCP WebSocket paths automatically).

Note: Discovery relies on mDNS/Bonjour broadcast. Inside WSL or containers the default NAT network often blocks discovery; switch WSL to mirrored networking mode (link) or run the container with a bridged network so broadcasts reach the local LAN.

Settings and Configuration

The extension provides several configuration options accessible via VS Code Settings (File > Preferences > Settings) or the Command Palette.

Settings Table

Example Configurations

Example 1: TCP Raw Socket (Default)

{
  "juliet.devenv.connectionType": "tcp-rawsocket",
  "juliet.devenv.host": "localhost",
  "juliet.devenv.dap.port": 1234,
  "juliet.devenv.lsp.port": 1235
}

Example 2: Unix Raw Socket

{
  "juliet.devenv.connectionType": "unix-rawsocket",
  "juliet.devenv.dap.socketPath": "/tmp/dap.sock",
  "juliet.devenv.lsp.socketPath": "/tmp/lsp.sock"
}

Example 3: Unix WebSocket

{
  "juliet.devenv.connectionType": "unix-websocket",
  "juliet.devenv.dap.socketPath": "/tmp/dap.sock",
  "juliet.devenv.lsp.socketPath": "/tmp/lsp.sock"
}

Example 4: TCP WebSocket

{
  "juliet.devenv.connectionType": "tcp-websocket",
  "juliet.devenv.host": "192.168.1.100",
  "juliet.devenv.dap.socketPath": "/juliet-romeo/dap",
  "juliet.devenv.lsp.socketPath": "/juliet-romeo/lsp",
  "juliet.devenv.dap.port": 443,
  "juliet.devenv.lsp.port": 443
}

N.B.: WebSocket URLs are automatically constructed as:

• wss://{host}{:port}{socketPath} when port is 443
• ws://{host}{:port}{socketPath} for other ports
• Port is omitted from URL if it's the default (80 for ws://, 443 for wss://)

Configuration Tips

• Workspace-specific settings: Configure different hosts/ports per project by setting at Workspace level
• User-level settings: Apply settings globally across all projects by setting at User level
• Load path management: Use the Devenv status bar menu ("Set Juliet load path" / "Add Juliet load path") for easier path configuration
• Terminal visibility: Enable runInTerminals to troubleshoot process issues
• Discovery picker: Use the target status bar item to rescan, switch, or save/remove targets; saved entries persist in juliet.devenv.savedTargets per workspace

Extension Commands

Command Palette

• Juliet: Restart Language Server - Restart the Juliet language client
• Juliet: Start juliet REPL in terminal - Open a Juliet REPL in an integrated terminal (Linux-only)
• Juliet: Get versions - Show Juliet/Romeo version details (Linux-only)
• Juliet: Set juliet load path - Configure the Juliet load path. Can also be accesses via the Devenv status bar menu
• Juliet: Add juliet load path - Append to the Juliet load path. Can also be accesses via the Devenv status bar menu
• Romeo: Restart RVM and Devenv - Restart managed runtime processes (Linux-only)
• Romeo: Debug: Show rvm and devenv terminals - Show managed process in integrated terminals (Linux-only)
• Romeo: Debug: Hide rvm and devenv terminals - Hide terminals for managed process (Linux-only)
• Romeo: Enable auto start of processes - Enable auto-start of the RVM and Devenv (Linux-only)
• Romeo: Disable auto start of processes - Disable auto-start of the RVM and Devenv (Linux-only)
• Romeo: Install Romeo package - Prompts the user to select the package to be installed (Linux-only)
• Romeo: Uninstall Romeo package - Uninstall romeo (Linux-only)
• Romeo: Update Romeo package - Uninstall romeo and installs a new user-selected package (Linux-only)

Editor title (Run/Debug buttons)

• Debug package - Editor title bar debug button for Juliet files
• Run package - Editor title bar run button for Juliet files

Editor context menu

• Juliet: Enable/Disable show active line - Toggle active-line highlighting
• Juliet: Enable/Disable follow motion pointer - Toggle following the motion pointer
• Juliet: Apply file edits - Apply stop-state edits to the running debug session
• Juliet: Auto pause/resume tasks on apply - Automatically pause/apply/resume tasks when applying edits
• Juliet: Disable auto pause/resume tasks on apply - Disable the automatically pause/apply/resume tasks when applying edits
• Juliet: Package load / unload / debug / list - Manage Juliet packages during a debug session

Limitations

Workspace limitations

Multi-root workspaces are not currently supported, only single workspace folder.

Multitask limitations

The pause/continue/step commands execute the request on a single task. The task is selected in "CALL STACK" debug window.

Hovering over a task in the task list also show the pause/continue buttons. Before pressing it, it is strongly recommended to select the entire task line first and then press pause/continue to ensure the request is executed on the correct task.