Skip to content

vscode-integration.md

Latest commit

 

History

History
72 lines (57 loc) · 3.83 KB

vscode-integration.md

File metadata and controls

72 lines (57 loc) · 3.83 KB

Integrate the BrightScript Simulator with VS Code

The BrightScript VS Code Extension can deploy apps directly to the BrightScript Simulator and attach the debugger for a fast authoring loop. This guide shows how to connect the tools and prepare a reusable debug configuration.

Prerequisites

  • BrightScript Simulator installed and running; it can be on another machine reachable over the network.
  • BrightScript VS Code Extension installed in VS Code.
  • A Roku/BrightScript project opened in VS Code with a manifest file at its root.

Prepare the Simulator

  1. Launch the BrightScript Simulator desktop application.
  2. Open the Settings Screen.
  3. In the Services section, confirm the services are enabled (all checkboxes marked) for App Installer (Web), ECP, and Remote Console (Telnet).
  4. If you change the Application Installer port or the password, make sure you restart the service (unmark and remark the checkbox) and take note the new values—you will use them in the launch.json configuration (section below).
  5. Keep the simulator running; the VS Code debugger connects to it over the configured ports.

Important

On Linux systems, due to OS restrictions, the Installer service can not be started on port 80, so the service is disabled by default. To enable it, you must specify a different port.

Create the VS Code Debug Configuration

  1. In VS Code, open the Run and Debug view and choose create a launch.json file.
  2. Pick BrightScript as the environment. VS Code creates (or updates) .vscode/launch.json in your workspace.
  3. Replace the generated configuration (or add a new entry) with the example below, adjusting folders or ports to match your project. The highlighted settings are required for the simulator integration.
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "BrightScript Debug: Launch",
            "type": "brightscript",
            "request": "launch",
            "host": "${promptForHost}",
            "packagePort": 80,
            "password": "${promptForPassword}",
            "rootDir": "${workspaceFolder}",
            "files": [
                "manifest",
                "source/**/*.*",
                "components/**/*.*",
                "images/**/*.*"
            ],
            "enableDebugProtocol": false,
            "rendezvousTracking": false
        }
    ]
}
  • host should point to the simulator's IP address; use localhost when the simulator runs on the same machine.
  • packagePort optional, must match the Application Installer service port configured in the simulator (default 80).
  • password should match the developer password set in the simulator (default rokudev).
  • rootDir should point to your project's root folder containing the manifest file.
  • files should include all source files and assets needed for your app.
  • enableDebugProtocol and rendezvousTracking must be set to false for compatibility with the simulator.

Run and Debug

  1. Build and package your project using VSCode BrightScript Extension by pressing F5 or the play button on the Run and Debug view.
  2. VSCode installs the latest build to the simulator, launches the channel, and attaches the debugger. Set breakpoints and inspect variables as usual.

Troubleshooting

  • Connection refused: Verify the simulator is running and that the installer port in launch.json match the simulator settings.
  • Upload failures: Confirm the Application Installer service is enabled and the password matches the simulator configuration (default rokudev).
  • Debugger stops immediately: Ensure you disabled enableDebugProtocol and rendezvousTracking; the simulator does not support those options being true.