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:
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