FSWatcher – Node.js daemon for triggering ANT tasks

This document describes the functionality and configuration of the FSWatcher Node.js daemon. This tool replaces the previously used Ant target runner VS Code extension.

Tool Description

FSWatcher is a lightweight Node.js CLI daemon distributed as an npm package.

FSWatcher:

Watches configured folders recursively.
Executes specified ANT targets.
Runs continuously until stopped (CTRL+C).

Unlike the VS Code ANT Target Runner extension, FSWatcher:

Does not depend on a specific IDE.
Works reliably in multi-project workspaces.
Can be used from CLI, VS Code tasks, or other automation tools.

Requirements

Node.js version 16 or higher
Access to the private Consultingwerk npm registry https://npm.consultingwerkcloud.com
Progress OpenEdge installation
Windows operating system

Instructions

Using FSWatcher in a workspace where it is configured

There are a few steps that need to be taken individually by all developers working with a workspace, in which the FSWatcher is configured, for it to be functional for them:

Go to https://npm.consultingwerkcloud.com and register an account with your company email address. Make sure the username you provide only has lower case letters.
Open a command prompt.
Configure the Consutingwerk npm package registry.

npm config set @consultingwerk:registry https://npm.consultingwerkcloud.com

Log in to the Consultingwerk package via CLI. When prompted provide your configured username and password.

npm login --registry https://npm.consultingwerkcloud.com

Open the workspace in which the FSWatcher is configured.
If the FSWatcher was configured to be run automatically upon opening the workspace, when you open it you may see a prompt in the bottom right asking - "Allow automatic tasks in this workspace?". Click “Allow”.

Now whenever you open the workspace you should see a new terminal being created and the FSWatcher package being run inside of it.

Configuring FSWatcher for a Project

The goal of this step is to allow FSWatcher to be executed via a CLI command inside a project.

Go to https://npm.consultingwerkcloud.com and register an account with your company email address. Make sure the username you provide only has lower case letters.
Open a command prompt.
Configure the Consutingwerk npm package registry.

npm config set @consultingwerk:registry https://npm.consultingwerkcloud.com

Log in to the Consultingwerk package via CLI. When prompted provide your configured username and password.

npm login --registry https://npm.consultingwerkcloud.com

Add a configuration file in the target project root titled fswatcher-config.json

Structure and example values:

{
  "antExecutable": " %DLC%/ant/bin/ant",
  "additionalLib": "%DLC%/pct/pct.jar",
  "watchFolders": [
    {
      "folder": ".",
      "patterns": [
        "**/{I*.cls,*BusinessEntity.cls,*Task.cls,*Service.cls,*Enum.cls,*Parameter.cls}"
      ],
      "antFile": "annotations.xml",
      "antTargets": ["ExtractClassAnnotationsVsCode"],
      "arguments": "-DautoTargetTriggerFilename=@{changedFile.Relative}",
      "delay": 2000
    }
  ]
}

To configure the FSWatcher for another project in the same workspace, simply add a second object in the watchFolders array with the desired configuration. Provide the folder and antFile paths relative to the path of the folder where the fswatcher-config.json is located.
You should run the FSWatcher form a shell with DLC set e. g. from proenv or alternatively, create a start-fswatcher.cmd script. If the script is not in the same folder as the JSON configuration file, you can add a --config path/to/fswatcher-config.json option to the npx command. Alternatively, the script can cd to the folder where the config file resides.

Example content:

@echo off

call [script that sets your DLC]

npx -y @consultingwerk/ant-target-runner

Configuring FSwatcher to Run Automatically

For FSwatcher to be run automatically upon opening the workspace a startup task must be added:

Open the workspace file (e. g. MyWorkspace.code-workspace) in a text editor
Modify the workspace file by adding an FSWatcher startup task

Example:

{
  "tasks": {
    "version": "2.0.0",
    "tasks": [
      {
        "label": "Start Watcher [Name of the project folder]",
        "type": "shell",
        "command": "start-fswatcher.cmd",
        "options": {
          "cwd": "${workspaceFolder:[Folder where your stard-fswatcher.cmd script is located]\\start-fswatcher.cmd }" 
        },
        "isBackground": true,
        "problemMatcher": [],
        "runOptions": {
          "runOn": "folderOpen"
        }
      }
    ],
  }
}

Restart VS Code.
Upon opening VS Code you may see a prompt in the bottom right - "Allow automatic tasks in this workspace?". Click “Allow”.
You should see a new terminal titled “Start Watcher [Project name]” automatically open and run the FSwatcher.

Disabling ANT Target Runner Extension

To prevent duplicate or conflicting executions, the VS Code Ant Target Runner VS Code extension should be disabled for projects using FSWatcher.

Steps:

Open the VS Code workspace.
Go to Extensions.
Locate Ant Target Runner extension.
Uninstall the extension.
Delete all build.auto files in the workspace.

Disabling ANT Builder in Developer Studio

If you are working in Developer studio, then you may have been using an Eclipse ANT Builder to execute the ANT target. To disable the ANT Builder in Eclipse you must:

Open your project in Developer Studio.
In the Project Explorer, right-click on the project and go to properties.
Go to Builders.
Click on the Extract Class Annotation Builder.
Click Remove.
Click Apply and Close.