9. Visual Studio Code integration

Halon has a fully-featured integration with Visual Studio Code that leverages Visual Studio Code Remote Development which allows you to connect to a container or remote machine (where Halon is installed) to work with it’s configuration, including linting and debugging it’s Halon script (HSL) source files.

Note

The Visual Studio Code integration currently only works with the componentized package, not the integrated package. When using the integrated package there is a fully-featured IDE (script editor) included in the web administration that can be used instead.

9.1. Extensions

Below is a list of the extensions we provide and whether they should be installed locally or remotely. If both options are marked it can be installed either locally or remotely depending on the use case.

Extension Local Remote Marketplace
Halon Configuration Packer Install
Halon Scripting Language Syntax   Install
Halon Scripting Language Linter   Install
Halon Scripting Language Debugger   Install

9.1.1. Configuration Packer

Provides a configuration packer for Halon. It also provides a linter for the configuration files.

Note

This extension can be installed either locally or remotely depending on the use case. When installed locally it can also be used to quickly setup a development environment.

Run the Halon: Build command to package the configuration files. If you don’t have an existing configuration you can run the Halon: Init command and select a configuration template.

If you want to exclude certain files inside src/files when packing the configuration you can do so by adding a halon.build.exclude workspace setting to your .vscode/settings.json file like this:

{
  "halon.build.exclude": [
    "modules/batv/README.md"
  ]
}

By default the linter will try to lint the configuration files using the latest JSON schemas version. If you’re running an older version of the MTA you can configure the linter to use an older version of the JSON schemas by adding a yaml.schemas workspace setting to your .vscode/settings.json file like this:

{
  "yaml.schemas": {
    "https://docs.halon.io/json-schemas/5.7-stable/smtpd.schema.json": "src/config/smtpd.yaml",
    "https://docs.halon.io/json-schemas/5.7-stable/smtpd-app.schema.json": "src/config/smtpd-app.yaml"
  }
}
_images/vscode-conf.png

The autocomplete and linter for the YAML configuration files in action

9.1.2. HSL Syntax

Provides syntax highlighting for Halon script (HSL) source files.

_images/vscode-syntax.png

The Halon script (HSL) syntax highlighting in action

9.1.3. HSL Linter

Provides a linter for Halon script (HSL) source files.

Note

This extension should only be installed remotely.

_images/vscode-linter.png

The Halon script (HSL) linter in action

9.1.4. HSL Debugger

Provides a debugger for Halon script (HSL) source files.

Note

This extension should only be installed remotely.

Launch configuration snippets are available under the Halon Scripting Language namespace when the extension has been installed. Use the Debug File snippet if you want to debug a HSL module inside the src/files folder using our script interpreter or the Debug Live Stage snippet if you want to debug the smtpd process when using blue-green testing.

If you open the .vscode/launch.json file that gets created you can add conditions to the Debug Live Stage snippet to limit which incoming connections the test configuration gets applied for, such as probability or remoteips:

{
  "name": "Debug Live Stage",
  "type": "halon",
  "request": "launch",
  "conditions": {
    "probability": 0.01,
    "remoteips": [
      "10.2.55.20"
    ]
  }
}
_images/vscode-debug.png

The Halon script (HSL) debugger in action

9.2. Setting up a development environment

To quickly setup a development environment using a container and Docker Desktop, simply install the Halon Configuration Packer extension locally, run the Halon: Init command and when the selection for Remote development comes up, pick the container option. After this, follow the instructions in the README.md file that opens up to get started.

See Developing inside a Container for more information about how this works.