XAnalyzer - XLang/XPL Debugger for VSCode

A VSCode extension for debugging XLang/XPL scripts and templates in nop-entropy applications.

Features

• Breakpoints: Set breakpoints in XLang/XPL files
• Stepping: Step into, over, and out of code
• Variables: Inspect local and global variables
• Call Stack: View the call stack and navigate between frames
• Expressions: Evaluate expressions and watch variables
• Conditional Breakpoints: Set breakpoints with conditions
• Log Points: Add log messages without stopping execution

Requirements

• VSCode 1.80.0 or higher
• A running nop-entropy application with debug server enabled
• Node.js (for running the extension)

Installation

From Source

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Compile the TypeScript code:

   npm run compile
   

4. Press F5 in VSCode to launch a new VSCode window with the extension loaded

From VSCode Marketplace (Coming Soon)

Search for "XLang Debugger" in the VSCode Extensions marketplace and click Install.

Configuration

launch.json

Create or edit .vscode/launch.json in your workspace:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "xlang",
      "name": "Launch XLang Debug",
      "request": "launch",
      "host": "localhost",
      "port": 8080
    }
  ]
}

Configuration Options

Settings

You can configure the extension behavior in VSCode settings:

• xlang.debug.logLevel: Log level (trace, debug, info, warn, error)
• xlang.debug.autoConnect: Automatically connect on startup

Usage

Starting a Debug Session

1. Start your nop-entropy application with the debug server enabled
2. Open an XLang/XPL file in VSCode
3. Press F5 or go to Run and Debug -> "Launch XLang Debug"
4. Set breakpoints by clicking in the gutter (left side of the editor)
5. Use the debug toolbar to control execution

Debug Actions

Breakpoints

• Regular Breakpoint: Click in the gutter to set/unset
• Conditional Breakpoint: Right-click -> Add Conditional Breakpoint
• Log Point: Right-click -> Add Log Point

Architecture

The extension consists of:

• RPC Client: Communicates with the nop-entropy debug server via TCP
• Debug Adapter: Implements the Debug Adapter Protocol (DAP)
• Variable Manager: Caches and expands variables for inspection
• Type Definitions: TypeScript types mapping Java types

Communication Protocol

The extension uses the SimpleRpc binary protocol to communicate with the Java debugger:

1. TCP socket connection to the debug server
2. Binary command encoding/decoding
3. Async RPC calls via IDebuggerAsync interface

Development

Project Structure

x-analyzer/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── debugAdapter/
│   │   └── debugSession.ts       # DAP session implementation
│   ├── rpc/
│   │   ├── client.ts             # RPC client
│   │   ├── binaryCommand.ts      # Binary protocol codec
│   │   └── debuggerProxy.ts      # Debugger proxy interface
│   ├── types/
│   │   ├── debugger.ts           # Debugger types
│   │   └── api.ts                # API types
│   └── variables/
│       └── variableManager.ts    # Variable management
├── package.json
├── tsconfig.json
└── README.md

Building

# Compile
npm run compile

# Watch mode
npm run watch

# Run tests
npm test

Referenced nop-entropy Files

• nop-dev-tools/nop-api-debugger/src/main/java/io/nop/api/debugger/IDebugger.java
• nop-dev-tools/nop-xlang-debugger/src/main/java/io/nop/xlang/debugger/XLangDebugger.java
• nop-dev-tools/nop-idea-plugin/src/main/java/io/nop/idea/plugin/debugger/XLangDebugConnector.java

Troubleshooting

Connection Refused

• Ensure the nop-entropy application is running
• Check that the debug server port is correct
• Verify firewall settings

Breakpoints Not Hitting

• Make sure the source file path matches the server path
• Check that the file is being executed in the debug session
• Verify the debugger is connected (check Debug Console for messages)

Variables Not Showing

• Ensure the program is paused at a breakpoint
• Try refreshing the variables view
• Check the Debug Console for error messages

License

MIT

Author

protagonisths

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.