Skip to content

Commit 17ae3ac

Browse files
chrisdpTwitchBronBron
chrisdp
and
TwitchBronBron
authored
Task/support for brightscript tasks with custom command variable resolving (#693)
Co-authored-by: Bronley Plumb <bronley@gmail.com>
1 parent 574611e commit 17ae3ac

9 files changed

Lines changed: 3160 additions & 4 deletions

‎README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ The extension is packed with features, but here are some highlights:
2121
- Integrated device logs and interactive console (see image below)
2222
- Catch errors in VSCode with the built in syntax checking. (Powered by the [BrighterScript](https://github.com/rokucommunity/brighterscript) language server)
2323
- Automatic rendezvous tracking when `logrendezvous` is enabled on the Roku device.
24+
- Powerful task system with interactive folder selection and advanced configuration options
2425
- Syntax highlighting, code formatting, symbol navigation, and [much more](https://rokucommunity.github.io/vscode-brightscript-language/features.html)
2526

2627
![Debugger Demo](https://user-images.githubusercontent.com/2544493/78854455-5e08c880-79ef-11ea-8eb4-1f2d74230842.gif)
@@ -41,6 +42,10 @@ For a full list of features and settings, please see our [documentation website]
4142
- [Code formatting](https://rokucommunity.github.io/vscode-brightscript-language/Editing/code-formatting.html) - How to set up code formatting and the different formatting options.
4243
- [Code Snippets](https://rokucommunity.github.io/vscode-brightscript-language/Editing/snippets.html) - A collection of useful code sippets
4344

45+
### Tasks
46+
47+
- [BrightScript Tasks](https://rokucommunity.github.io/vscode-brightscript-language/brightscript-tasks.html) - Automate your development workflow with BrightScript tasks
48+
4449
### Debugging
4550

4651
- [Basic project setup](https://rokucommunity.github.io/vscode-brightscript-language/Debugging/index.html) - Launching and debugging your local project on a Roku device.

‎docs/brightscript-tasks.md‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# BrightScript Tasks
2+
3+
The BrightScript language extension provides a task system that integrates with VS Code's task runner, allowing you to automate common development workflows like building, testing, and linting.
4+
5+
## Features
6+
7+
- Custom shell commands with variable substitution
8+
- Interactive folder selection with glob patterns
9+
- Environment variables and custom working directories
10+
- Problem matcher integration for error detection
11+
- Background task support for watchers
12+
13+
## Basic Task Configuration
14+
15+
Tasks are defined in `.vscode/tasks.json` in your workspace. Here's a simple example:
16+
17+
```json
18+
{
19+
"version": "2.0.0",
20+
"tasks": [
21+
{
22+
"type": "brightscript",
23+
"label": "Build Project",
24+
"command": "npx bsc"
25+
}
26+
]
27+
}
28+
```
29+
30+
### Required Properties
31+
32+
- **type**: Must be `"brightscript"` to use the BrightScript task provider
33+
- **label**: Display name shown in the task picker
34+
- **command**: The shell command to execute
35+
36+
## Variable Substitution
37+
38+
BrightScript tasks support variable substitution in the `command` field. Variables are resolved before the command is executed.
39+
40+
### Using `${folderForFile: <glob>}`
41+
42+
The `${folderForFile: <glob>}` variable finds files matching a glob pattern and resolves to the directory containing those files. This is useful in monorepos or multi-project workspaces.
43+
44+
**Example: Build a specific project**
45+
46+
```json
47+
{
48+
"type": "brightscript",
49+
"label": "Build Selected Project",
50+
"command": "cd ${folderForFile: **/bsconfig.json} && npx bsc"
51+
}
52+
```
53+
54+
When you run this task:
55+
- If one `bsconfig.json` is found, it uses that directory automatically
56+
- If multiple are found, you get a quick pick menu to select which project
57+
58+
**Common glob patterns:**
59+
60+
| Pattern | Matches |
61+
|---------|---------|
62+
| `**/bsconfig.json` | Any `bsconfig.json` file at any depth |
63+
| `apps/**/package.json` | `package.json` files under the `apps` directory |
64+
| `*.config.js` | Config files in the root directory only |
65+
66+
**Note**: Files in `node_modules` are automatically excluded.
67+
68+
## Advanced Configuration
69+
70+
### Environment Variables
71+
72+
Add environment variables available to your command:
73+
74+
```json
75+
{
76+
"type": "brightscript",
77+
"label": "Build with Custom Env",
78+
"command": "npx bsc",
79+
"options": {
80+
"env": {
81+
"NODE_ENV": "production"
82+
}
83+
}
84+
}
85+
```
86+
87+
### Custom Working Directory
88+
89+
```json
90+
{
91+
"type": "brightscript",
92+
"label": "Build from Subdirectory",
93+
"command": "npx bsc",
94+
"options": {
95+
"cwd": "${workspaceFolder}/apps/my-roku-app"
96+
}
97+
}
98+
```
99+
100+
## Problem Matchers
101+
102+
Problem matchers parse command output to detect errors and warnings. Here's a basic example for BrighterScript compiler output:
103+
104+
```json
105+
{
106+
"type": "brightscript",
107+
"label": "Compile",
108+
"command": "npx bsc",
109+
"problemMatcher": {
110+
"owner": "brightscript",
111+
"fileLocation": "relative",
112+
"pattern": {
113+
"regexp": "^(.*)\\((\\d+),(\\d+)\\):\\s+(error|warning)\\s+(.*)$",
114+
"file": 1,
115+
"line": 2,
116+
"column": 3,
117+
"severity": 4,
118+
"message": 5
119+
}
120+
}
121+
}
122+
```
123+
124+
## Background Tasks
125+
126+
Background tasks are useful for file watchers or development servers:
127+
128+
```json
129+
{
130+
"type": "brightscript",
131+
"label": "Watch",
132+
"command": "npx bsc --watch",
133+
"isBackground": true
134+
}
135+
```
136+
137+
## Pre-Launch Tasks
138+
139+
Use tasks as pre-launch actions to build your project before debugging:
140+
141+
```json
142+
{
143+
"type": "brightscript",
144+
"name": "Launch on Roku",
145+
"request": "launch",
146+
"host": "${promptForHost}",
147+
"password": "${promptForPassword}",
148+
"preLaunchTask": "Build Project"
149+
}
150+
```
151+
152+
## Complete Example
153+
154+
Here's a basic `tasks.json` for a monorepo workflow:
155+
156+
```json
157+
{
158+
"version": "2.0.0",
159+
"tasks": [
160+
{
161+
"type": "brightscript",
162+
"label": "Build Selected Project",
163+
"command": "cd ${folderForFile: **/bsconfig.json} && npx bsc",
164+
"group": {
165+
"kind": "build",
166+
"isDefault": true
167+
}
168+
},
169+
{
170+
"type": "brightscript",
171+
"label": "Watch Selected Project",
172+
"command": "cd ${folderForFile: **/bsconfig.json} && npx bsc --watch",
173+
"isBackground": true
174+
}
175+
]
176+
}
177+
```
178+
179+
## Troubleshooting
180+
181+
**Task not found:**
182+
- Ensure `type` is set to `"brightscript"`
183+
- Verify `tasks.json` has valid JSON syntax
184+
185+
**Variable not resolving:**
186+
- Check that files matching the glob pattern exist
187+
- Remember that `node_modules` is excluded
188+
189+
**Command not executing:**
190+
- Check the terminal output for errors
191+
- Verify the command works in a regular terminal
192+
- Ensure required programs are in your PATH
193+
194+
## Best Practices
195+
196+
- Use descriptive task labels
197+
- Add problem matchers for instant error feedback
198+
- Set default build and test tasks for keyboard shortcuts
199+
- Use the `${folderForFile}` variable for monorepo flexibility
200+
201+
## See Also
202+
203+
- [VS Code Tasks Documentation](https://code.visualstudio.com/docs/editor/tasks)
204+
- [Variable Substitutions](./variable-substitutions.md)
205+
206+
## Supported Variables
207+
208+
| Variable | Description | Example Value |
209+
|----------|-------------|---------------|
210+
| **Workspace Variables** | | |
211+
| `${workspaceFolder}` | Path of the workspace folder | `/Users/user/project` |
212+
| `${workspaceFolderBasename}` | Name of the workspace folder | `project` |
213+
| `${fileWorkspaceFolderBasename}` | Name of workspace folder containing active file | `my-app` |
214+
| **File Variables** (require an active file) | | |
215+
| `${file}` | Full path of the currently opened file | `/Users/user/project/src/main.brs` |
216+
| `${fileWorkspaceFolder}` | Workspace folder of the currently opened file | `/Users/user/project` |
217+
| `${relativeFile}` | Current file relative to workspace folder | `src/main.brs` |
218+
| `${relativeFileDirname}` | Current file's directory relative to workspace | `src` |
219+
| `${fileBasename}` | Current file's basename | `main.brs` |
220+
| `${fileBasenameNoExtension}` | Current file's basename without extension | `main` |
221+
| `${fileExtname}` | Current file's extension | `.brs` |
222+
| `${fileDirname}` | Current file's directory path | `/Users/user/project/src` |
223+
| `${fileDirnameBasename}` | Current file's directory name | `src` |
224+
| **Editor Variables** (require an active editor) | | |
225+
| `${lineNumber}` | Current line number in active file (1-based) | `42` |
226+
| `${columnNumber}` | Current column number in active file (1-based) | `15` |
227+
| `${selectedText}` | Currently selected text in active file | `function main()` |
228+
| **System Variables** | | |
229+
| `${userHome}` | User's home directory | `/Users/user` |
230+
| `${cwd}` | Current working directory of VS Code | `/Users/user/project` |
231+
| `${execPath}` | Path to VS Code executable | `/Applications/VSCode.app` |
232+
| `${pathSeparator}` | OS-specific path separator | `/` (macOS/Linux) or `\` (Windows) |
233+
| `${/}` | Shorthand for `${pathSeparator}` | `/` or `\` |
234+
| **Custom Variables** | | |
235+
| `${folderForFile: <glob>}` | Directory containing file(s) matching glob pattern | `/Users/user/project/apps/app1` |

‎docs/features.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,11 @@ priority: 2
1616
- Injection of the Roku Advanced Layout Editor(RALE) task from a single user managed version
1717
- This helps avoid committing the tracker to you repo and also lets you manage what version you want installed rather then other users on the project
1818
- See ([Extension Settings](./extension-settings.html) and [RALE Support](./Debugging/rale.html) for more information)
19+
- BrightScript tasks with advanced features ([learn more](./brightscript-tasks.html))
20+
- Interactive folder selection with `${folderForFile: <glob>}` variable
21+
- Support for custom shells, environment variables, and working directories
22+
- Problem matcher integration for error detection
23+
- Background task support for watchers and dev servers
1924
- Publish directly to a roku device from VSCode (provided by [roku-deploy](https://github.com/RokuCommunity/roku-deploy))
2025
- Also supports zipping and static file hosting for Component Libraries ([click here](./Debugging/component-libraries.html) for more information)
2126
- Basic symbol navigation for document and workspace ("APPLE/Ctrl + SHIFT + O" for document, "APPLE/Ctrl + T" for workspace)

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ The extension is packed with features, but here are some highlights:
1313
- Full debugger support including breakpoints, variable inspection, and more
1414
- Integrated telnet logs and interactive console
1515
- client-side syntax checking powered by the [BrighterScript](https://github.com/rokucommunity/brighterscript) language server
16+
- Powerful task system with interactive folder selection and advanced configuration
1617
- syntax highlighting, code formatting, symbol navigation, and [much more](features.html)

‎package.json‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,34 @@
148148
"onLanguage:xml",
149149
"workspaceContains:**/manifest",
150150
"workspaceContains:**/bsconfig.json",
151-
"onDebug"
151+
"onDebug",
152+
"onTaskType:brightscript"
152153
],
153154
"contributes": {
155+
"taskDefinitions": [
156+
{
157+
"type": "brightscript",
158+
"required": [
159+
"command"
160+
],
161+
"properties": {
162+
"command" : {
163+
"description": "The command to run for this task, you can use substitutions such as ${folderForFile: **/bsconfig.json}",
164+
"anyOf": [
165+
{
166+
"enum": [
167+
"npx bsc --cwd src",
168+
"npx bsc --cwd ${folderForFile: **/bsconfig.json}"
169+
]
170+
},
171+
{
172+
"type": "string"
173+
}
174+
]
175+
}
176+
}
177+
}
178+
],
154179
"viewsContainers": {
155180
"activitybar": [
156181
{

0 commit comments

Comments
 (0)