Chapter 34. Custom Scripts

DVT Custom Scripts are scripts run as tasks with access to the Visual Studio Code and JavaScript APIs, having the purpose of automating jobs in your environment.

They are created based on automatically collected scripts that fall into two categories:

1. Startup Scripts

These can be defined: - in the .dvt directory in the project, by creating startup.dvt.js or *.startup.dvt.js files - by pointing the DVT_CODE_STARTUP_SCRIPT environment variable to a script without naming constraints

These are run automatically at startup, when the DVT.customScripts.automaticallyRunAtStartup preference is enabled.

2. Custom Scripts

*.dvt.js files that can be defined anywhere in the project.

Examples:

1. Change the value of a preference at startup

*.startup.dvt.js

(async () => {
     print("Value of 'editor.insertSpaces' before: " + vscode.workspace.getConfiguration().get("editor.insertSpaces"));
     await vscode.workspace.getConfiguration().update("editor.insertSpaces", false, true);
     print("Value of 'editor.insertSpaces' after: " + vscode.workspace.getConfiguration().get("editor.insertSpaces"));
})();

print(<message>) - print messages in the terminal
vscode.workspace.getConfiguration().get(<setting_id>) - get the value of setting_id from configuration
vscode.workspace.getConfiguration().update(<setting_id>, <value>, <configuration_target>) - update the value of setting_id in the configuration_target, where:
- setting_id is a string corresponding to the ID of the setting
- value is an object corresponding to the new value of the setting
- configuration_target can be:
  - true - updates Global settings
  - false - updates Workspace settings
  - undefined or null - updates to Workspace folder settings if configuration is resource specific, otherwise to Workspace settings

2. Format files from a directory

format_dir.dvt.js

(async () => {
     const files = await vscode.workspace.findFiles("**/<relative_directory_path>/*.sv");
     for (const file of files) {
         print("Formatting " + file.path + "...");
         await vscode.window.showTextDocument(file);
         await vscode.commands.executeCommand('editor.action.formatDocument');
         await vscode.commands.executeCommand('workbench.action.files.save');
         await vscode.commands.executeCommand('workbench.action.closeActiveEditor');
     };
})();

vscode.workspace.findFiles(<search_pattern>) - find all the files that match the search_pattern (a glob pattern that defines the files to search for)
vscode.window.showTextDocument(<file_URI>) - open the file with the file_URI
vscode.commands.executeCommand(<command_ID>, <arguments>) - executes the command denoted by the given command_ID, to which you can optionally pass arguments

To configure the script being run for a specific task, you can define a custom task with input variables in the tasks.json file. This file can be automatically generated using the "Tasks: Configure Tasks" command. Select "Create tasks.json file from template", then "Others" and a tasks.json file is generated in the .vscode directory, containing a generic task which you can further tune in order to run a custom script.

Example:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "DVT Custom Script",
            "type": "shell",
            "command": "${input:run_script_with_args}",
        }
    ],
    "inputs": [
        {
            "type": "command",
            "id": "run_script_with_args",
            "command": "dvt.custom.script",
            "args": [
                "custom_script.js",
                "arg_1",
                "arg_2"
            ]
        }
    ]
}

The task's properties have the following semantic:

label is an arbitrary name for the task, used in the user interface
type can be shell or process
command must have the ${input:<variable_id> syntax

Also, additional configuration attributes are necessary for the input entry:

type must be command
id must be the same with <variableID> from the command field of the task
command must be dvt.custom.script
args must be a list containing the path to the script as the first element and the arguments which will be passed on to the script

Note: The script for the command can be specified using:

an absolute path
a path containing environment variables
a relative path which will be solved based on the current workspace

Example - Automatically generate the build configuration file

tasks.json

{
     "version": "2.0.0",
     "tasks": [
         {
             "label": "Generate default.build",
             "type": "shell",
             "command": "${input:DVT_Custom_Script}"
         }
     ],
     "inputs": [
         {
             "id": "DVT_Custom_Script",
             "type": "command",
             "command": "dvt.custom.script",
             "args": [
                 ".dvt/gen_default_build.dvt.js",
                 "ius.irun",
                 "dvt_filelist.f",
                 "subsystem_top"
             ]
         }
     ]
}

gen_default_build.dvt.js

(async () => {
     const buildConfigPath = path.join(vscode.workspace.rootPath, <path_to_build_config>);
     let buildConfigContent = '';
     buildConfigContent += "+dvt_init+" + args[0] + "\n";
     buildConfigContent += "-f " + args[1] + "\n";
     buildConfigContent += "-top " + args[2] + "\n";
     fs.writeFileSync(buildConfigPath, buildConfigContent);
})();

args - the arguments passed on to the dvt.custom.script command
fs.writeFileSync(<file_path>, <file_content>) - writes file_content to the file at file_path and creates it if it does not exist