ECL for Visual Studio Code

For list of latest changes, please see the Change Log at the main GitHub repository.

This extension adds rich language support for HPCC Systems ECL language (for the HPCC-Platform) to VS Code, including:

• Syntax highlighting
• Auto completion
• Client tools discovery and integration
• HPCC-Platform server support
• Integrated result viewer

Recent Highlights

v2.38.x

• Improved KEL client-tool discovery, including installations found in HPCC Systems locations and the local Maven repository.
• Added the kel.kelPath setting to select a preferred KEL installation instead of using automatic detection.
• Added clearer progress, completion, failure, and diagnostic feedback for KEL syntax checking and ECL generation.

v2.30.x

• Added ecl.preferredECLWatch setting, allows user to nominate preferred version of ECL Watch when opening "external" pages.

v2.24.x

• Added context menu to ECL bundles and ECL Client Tools
• Added ecl.WUShowResults setting, allows user to control how results are displayed after submitting a workunit.

v2.23.x

• Added ecl.submitNoArchive command, submits raw content of editor to server without creating an archive first.
• Added ecl.pingInterval setting, allows user to change or disable the "server alive" ping.
• Updated shift+F1 help to use new HPCC Systems website and include the Standard Library.

v2.19.x

• Added ecl.saveOnSyntaxCheck and ecl.saveOnSubmit option to ECL Settings (defaulting to off to match ECL IDE behaviour).

v2.15.x

• Add path option to launch configuration (to assist with proxy servers).

v2.14.x

• Add Copy WUID context menu.

v2.13.x

• Add ecl.forceProxySupport setting.

v2.12.x

• Added extra support for Trustwave CA authority.
• Fixed issue with rejectAuthorized: false being ignored.
• Updated translations, added FR locale.
• Added "Copy as ECL ID" command to explorer and editor tab context menus.

v2.11.x

• Added "Import MOD file" command

v2.10.x

• Enhanced digital signature support:
  • ECL: Verify ECL Signature

v2.9.x

• KEL:
  • Optionally use grammar for syntax as you type checking (now off by default).
  • Improved syntax highlighting
  • Default syntax checking "on open" to true

v2.8.x

• Added digital signature support:
  • ECL: Sign ECL

v2.7.x

• Preliminary localisation support:
  • en
  • zh
  • pt-br
  • es

v2.6.0

• Added HPCC resources page:
  • List of available bundles:
    • Install
    • Uninstall
    • Open homepage
  • List of available client tools
    • Select (force) specific version
    • Deselect forced version
    • Open terminal for specific version
    • Open download page for Client Tools

v2.5.0

• Added context menu items for Workunits in the Workunit Tree:
  • Abort Workunit (only available for running WUs)
  • Delete Workunit (Only available for completed WUs)

v2.4.0

• Added result viewer to bottom pane
• Added "Copy Results as ECL"

v2.3.0

• Added list of "found" logical files to Insert Record Definition

v2.2.0

• Added Insert Record Definition menu item

v2.1.0

Reworked submission process:

• Launch configuration:
  • Simplified
  • Can be selected from the status bar
  • Can be pinned to specific ECL files
• Target Cluster:
  • Can be selected from the status bar
  • Can be pinned to specific ECL files
• Submit / Compile now available from:
  • Context menu
  • Top of editor
• Recent Workunits:
  • Tree view of recent workunits
  • Toggle between "Mine" and "All"
  • Open in external browser icon added to several locations

Quick Start

Version 2.x introduces a new streamlined submission process. The "old" Run/Debug pane support has been deprecated and will be removed in the future.

1. Open folder
2. Open ECL file
3. Create Launch Configuration (if needed)
4. Select the target by:
   • Clicking the "Launch Configuration" in the status bar
   • Optionally clicking on the "Target Cluster" in the status bar
5. Monitor Workunit in the "Workunit History" pane
6. Click on Workunit to view results / issues in the bottom pane

ECL

Secure Credential Storage

Important: As of version 2.33.0, the extension now uses VS Code's secure storage for HPCC Platform credentials instead of storing passwords in plaintext in your launch configuration files.

What This Means for You

• Your passwords are now encrypted using your operating system's native credential manager (Windows Credential Manager, macOS Keychain, or Linux Secret Service)
• No more plaintext passwords in workspace files that could accidentally be committed to version control
• Automatic migration: Existing passwords are automatically moved to secure storage on first use
• Stay logged in across VS Code sessions without re-entering credentials

What You Need to Do

Nothing! The migration happens automatically. When you connect to an HPCC Platform:

1. If a password exists in your launch configuration, it will be securely stored and removed from the file
2. For new connections, you'll be prompted for credentials which will be securely saved
3. Your credentials persist across VS Code restarts

You can safely remove any "password" fields from your launch.json files if you prefer.

AI / Chat Integration

The extension contributes the ECL chat participant (chat.ecl) and Language Model tools registered in src/ecl/lm/tools.ts. The participant can:

• Answer ECL language and standard-library questions using the bundled documentation vector index.
• Use selected text or the active ECL editor as bounded workspace context.
• Review ECL for portable correctness and performance risks.
• Syntax-check concrete ECL with the configured HPCC Client Tools connection.
• Compile generated functions, macros, and modules with a BWR integration harness.
• Search logical files and inspect connected HPCC workunits, errors, archived ECL, and metrics.

Generated or modified ECL follows a review then syntax-check workflow. Callable constructs also receive an integration compile when a representative harness can be generated. The assistant reports pass, conditional_pass, fail, or unavailable; it does not claim that code is verified when client tools or a platform connection are unavailable.

The ECL participant never submits or executes generated code as part of verification. Workspace source and compiler output are provided to the selected language model as request context. Use ecl.ai.workspaceContextCharacters to limit how much active-editor source is included.

NOTE: These features depend on the VS Code Language Model / Chat APIs which are still evolving. Behavior may change in future VS Code versions.

Copilot Chat Integration

Ask the ECL participant directly:

Example:

@ecl Review the selected JOIN, fix high-severity findings, and verify the result.

Syntax and integration checks require an active HPCC configuration with discoverable client tools. Documentation and static review remain available without a platform connection.

ECL Commands

The following ECL specific commands are available. Note: These commands will not be active until an ECL file has been opened (as this triggers the extension to load). To activate a command either use its associated hotkey or press ctrl/cmd+shift+p and type ECL this will present a filtered list of the ECL specific commands:

Global:

Command	Shortcut	Description
Syntax Check All Files	shift+F7	Save All + check syntax of all files.
Syntax Clear	ctrl/cmd+F7	Clear all previously reported ECL Syntax Check results
Import '.mod' file		Import MOD file into workspace
Language Reference Website		Opens the ECL language reference website in external browser
Terminal		Opens ECL Client Tools Terminal Session

Within the ECL Code Editor:

Command	Shortcut	Description
Submit	F5	Submit ECL
Compile		Compile ECL
Syntax Check	F7	Save and check syntax of current file
Submit (No Archive)	ctrl/cmd+F5	Submit raw ECL without creating an archive
Verify ECL Signature		Verify ECL Digital Signature
Language Reference Lookup	shift+F1	For the currently selected text, search the online ECL language reference
Insert Record Definition	ctrl/cmd+R	Fetches record definition for given logical file

Within the ECL Code Editor Tab Context Menu:

Command	Shortcut	Description
Copy as ECL ID		Copy path as Qualified ECL ID

Within the Workunit Tree Title Bar:

Command	Shortcut	Description
My workunits		Toggle between "My" and "All" Workunits
All workunits		Toggle between "My" and "All" Workunits
Refresh		Refresh Tree
ECL Watch		Launch ECL Watch in external browser
Switch Platform		Switch HPCC Platform instance (launch configuration)

Within the Workunit Tree:

Command	Shortcut	Description
Copy WUID		Copy workunit ID to clipboard
Abort Workunit		Abort running workunit
Delete Workunit		Delete completed workunit

Within the Explorer Tree Context Menu (ecl files only):

Command	Shortcut	Description
Copy as ECL ID		Copy path as Qualified ECL ID

Within the Status Bar

Command	Shortcut	Description
Launch Configuration		Click to select launch configuration
Target Cluster		Click to select target cluster
Pin		Pin current launch configuration and target cluster to current document
Client Tools		Click to select client tools version

Within the Result View

All commands in the Result View are available via context menu.

Command	Notes
Copy Column as ECL Set	Right Click on Column Header
Copy Row as ECL	Right Click in Result Body
Copy All as ECL	Right Click in Column Header or Result Body

Testing

Unit Tests (Vitest)

Purpose: Validate logic (utilities, transformations) quickly without starting a VS Code Extension Host.

Run in watch mode:

npm run test-vitest

Run once:

npm run test-run

Run with coverage:

npm run test-coverage

Run the VS Code integration tests:

npm run test-integration

Configuration lives in vitest.config.ts (jsdom environment). Avoid importing heavy VS Code APIs directly—wrap them so they can be mocked for unit tests.

Manifest Assertions

test/manifest.test.ts validates that required activation events and core commands are present in package.json without launching VS Code.

Full Pipeline

Runs lint -> build -> unit tests.

npm test

ECL Settings

The following Visual Studio Code settings are available for the ECL extension. These can be set in user preferences (ctrl/cmd+,) or directly in your current workspace (.vscode/settings.json):

  // Override eclcc auto detection.
  "ecl.eclccPath": ""

  // eclcc arguments.
  "ecl.eclccArgs": [],

  // eclcc syntax check arguments.
  "ecl.eclccSyntaxArgs": [],

  // Write eclcc log file to specified file.
  "ecl.eclccLogFile": ""

  // Run 'eclcc -syntax' on save.
  "ecl.syntaxCheckOnSave": true

  // Run 'eclcc -syntax' on load.
  "ecl.syntaxCheckOnLoad": true

  // Additional folders to use when resolving IMPORT statements.
  "ecl.includeFolders": []

  // Add '-legacy' argument to eclcc.
  "ecl.legacyMode": false

  // Debug level logging (requires restart).
  "ecl.debugLogging": false

  // Show results after submitting a workunit.
  "ecl.WUShowResults": internal | external | disabled

  // Force global 'proxySupport' to 'fallback'
  "ecl.forceProxySupport": false

  // Save file prior to syntax check
  "ecl.saveOnSyntaxCheck": false

  // Save file prior to submission
  "ecl.saveOnSubmit": false

  // Preferred version of ECL Watch (default v9).
  "ecl.preferredECLWatch": v9 | v5

ECL Launch Settings

Submitting ECL using VS-Code requires specifying the target environment within the VS Code launch.json (pressing F5 will prompt you to auto create a skeleton file if none exists):

// Default ECL Launch Configuration
{
  "name": "localhost",
  "type": "ecl",
  "request": "launch",
  "protocol": "http",
  "serverAddress": "localhost",
  "port": 8010,
  "targetCluster": "hthor",
  "path": "",
  "abortSubmitOnError": true,
  "rejectUnauthorized": true,
  "resultLimit": 100,
  "timeoutSecs": 60,
  "user": "vscode_user",
  "password": ""
}

KEL

KEL is an optional language that can generate ECL.

KEL Commands

The following KEL specific commands are available. Note: These commands will not be active until a KEL file has been opened (as this triggers the extension to load). To activate a command either use its associated hotkey or press ctrl/cmd+shift+p and type KEL this will present a filtered list of the KEL specific commands:

Within the KEL Code Editor:

• Syntax Check [F7] - Save + check syntax of current file.
• Generate ECL [F5] - Save + generate ECL files.
• Reveal Generated ECL - Open the generated ECL folder in the file explorer.

Within the Status Bar

Click on KEL Client Tools Version

• Select Client Tools Version - Select Client Tools Version from available options.

KEL Settings

The following Visual Studio Code settings are available for the KEL extension. These can be set in user preferences (ctrl/cmd+,) or directly in your current workspace (.vscode/settings.json):

KEL is auto-detected from supported HPCC Systems installations and the local Maven repository. Set kel.kelPath to use a specific KEL.jar; selecting a client-tools version also stores that preferred path.

  // Java runtime arguments (e.g. -Xmx12G).
  "kel.javaArgs": []

  // Override KEL auto detection with a preferred KEL.jar path.
  "kel.kelPath": ""

  // Check syntax on save.
  "kel.syntaxCheckOnSave": true

  // Generated ECL location (Same Folder | Child Folder)."
  "kel.generateLocation": "Same Folder"

  // "Generate ECL on save."
  "kel.generateOnSave": false

  // Check syntax on load.
  "kel.syntaxCheckOnLoad": true

  // Check syntax with KEL grammar (fast)
  "kel.syntaxCheckFromGrammar": false

Building and Debugging the Extension

To set up a development environment for debugging the ECL for VS Code extension:

cd /Some/Dev/Folder/
git clone https://github.com/hpcc-systems/vscode-ecl
cd vscode-ecl
git submodule update --init --recursive
npm install

At which point you can open the vscode-ecl folder within VS Code.

Next start the background build process by pressing ctrl+shift+b (which will run the default build command in .vscode/tasks.json)

At which point you can edit the sources and launch debug sessions via F5 and included launch configurations.

License

Apache-2.0