Guide to using VS Code tasks

[Hezkore]

An extensive guide to using VS Code tasks and the ./vscode folder

Tasks might look and sound scary, but they're really nothing to fear and will make your life a lot easier when dealing with bigger projects.
They're really nothing more than simple shell/bash/cli/terminal commands you can tell VS Code to perform in steps.

Having said that!

Before you start using tasks, it's recommend that you at least have a general idea of how to use the VS Code extension itself and how the BlitzMax compiler works, or at least what commands it wants.
This also means you should be able to compile release builds and debug builds, how to use the build options in the 'BlitzMax View', the 'Problems View', and how to open folders in VS Code.
It's also highly recommended that you know how .json files are structured, as it's what VS Code use for most things.

If you feel like you have a decent grasp on all of this, then you're ready for tasks!
If not, you can read guide #10 on how to get started using the extension.

Baby steps

Let's start with explaining a few VS Code related things.

All of the information here will only apply to VS Code workspaces and folders.
A "folder" project in VS Code is what you get when you use the File > Open Folder option.
99% of the time File > Open Folder is how you'll open your project.
A "workspace" project is a bit more advanced (not a lot though) and is basically a collection of multiple folder projects.
You don't have to worry about workspaces right now, just remember that File > Open Folder is what you'll want to use for anything serious, while File > Open File is only really used for some quick testing and prototyping.
There's also no need to use the File > Save Workspace As... option, unless you've added multiple folder projects together.

Also note that VS Code uses the term "folder" and "workspace" interchangeably.
So don't get confused when VS Code mentions "workspace settings" when you've only got a "folder" project open.

VS Code will use the root of directory your folder project to store VS Code related settings and options.
These will appear as separate files located in <your_project_root>/.vscode/ when needed.
For example, you can alter your VS Code settings and have those changes only apply to your current project folder.
(File > Preferences > Settings - click 'Workspace')
This would in turn create a <your_ project_root>/.vscode/settings.json file.
All of the files located in <your_ project_root>/.vscode/ are humanly readable and you're free to open them up and change things around.

If things start to act weird and you want a total reset of your project specific settings; it's completely fine to remove the entire <your_ project_root>/.vscode/ folder.
VS Code will just re-generate any needed files.

Okay but I thought this was about tasks?

We're getting there!

Tasks behave similarly to the previously mentioned project specific settings.
But instead of a settings.json file, they'll use a <your_ project_root>/.vscode/tasks.json file.
When using the BlitzMax NG extension it doesn't really matter if you have a tasks.json file, as the extension tries to be smart and generate a tasks.json file for you if it's needed, otherwise it'll use an "internal task".
This is not the case with other language extensions in VS Code, where you'll always have to setup a tasks to compile your code.
But either way, let's create our own task from scratch!

Toying with tasks

Create a new folder called tasks_test, open the folder in VS Code using File > Open Folder and create a new file by right clicking the tree view in the 'Explorer' to the left and selecting New File, name it something like hello_world.bmx.
The file doesn't need any content right now.

We'll create a new task from scratch (you can - and should! - use a template later).
Right click the tree view in the 'Explorer' again, and select New Folder and name it .vscode.
Right click your new .vscode folder in the 'Explorer' and select New File, name it tasks.json and then double click to open it.
All of these steps aren't actually needed as you'll most likely use a template to create the tasks.json file.
But I want to keep the automation to a minimum here, so every layer of the process becomes as clear as possible.

The basic syntax of any tasks.json file is this:

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "<type_of_task>",
			"label": "<name_of_task>"
			// options
		},
		
		{
			"type": "<type_of_task>",
			"label": "<name_of_another_task>"
			// options
		}
	]
}

type sets the underlying logic for the task.
An example type would be shell for running basic shell/bash/cli/terminal commands.
All of the different extension you install for VS Code can add more types.
The BlitzMax NG VS Code extension adds the bmx task type, which really doesn't do much more than to make it easier for you to call the BlitzMax compiler.

label is used to identify the task, and can really be anything you want.

Notice the line // options.
Every task type provides its own unique set of options.
If you remove // options and trigger auto complete on that line by pressing ctrl + space, you'll be presented with all the available options for that task type.
You can also hover any option to get some more information.
(pro tip: you can press ctrl + space again to toggle info in the auto complete list)

Let's make a very simple task using the shell type.

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "shell",
			"label": "My shell task",
			
		}
	]
}

A task doesn't usually do anything on its own, we need to enter some options.
Let's use ctrl + space to see what it has to offer.
In the auto complete list you'll find command with the info "The shell command to be executed. Array items will be joined using a space character".
That sounds good, let's use that!

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "shell",
			"label": "My shell task",
			"command": ["echo Hello World"]
		}
	]
}

As mentioned in the intro, tasks are nothing more than calls to your standard shell/bash/cli/terminal.
That means that things like echo Hello World will work exactly like you expect.

Let's run our new task!
Click Terminal > Run Task... and select "My shell task".
You'll probably get prompted with an option to "Continue without scanning the task output".
This is totally fine, just hit enter.
This happens because we haven't specified a "problemMatcher" for our task, but more about that in a minute!

Notice that a terminal view appears at the bottom of VS Code when you run your task.
This is your terminal executing the task and printing any output.
You should see "Hello World" in it.

Congratulations, you've just made your very first task!

I'll quickly show you can specify options depending on OS as well.

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "shell",
			"label": "My shell task",
			
			"linux": {
				"command": "echo Hello from Linux"
			},
			
			"windows": {
				"command": "echo Hello from Window"
			},
			
			"osx": {
				"command": "echo Hello from MacOS"
			}
		}
	]
}

How does this make things easier?

Okay, so maybe this task is utterly pointless...
But let's worry about that later and for now have a look at the BlitzMax bmx task type!

Start by entering this into your hello_world.bmx file:

Framework brl.standardio
Print("Hello World")

And then we'll jump back to our tasks.json file.

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "bmx",
			"label": "My bmx task"
		}
	]
}

Notice that the "Problem" view at the bottom says we have at least 2 errors.
If you jump over to that view (click the problems tab or press ctrl + shift + m), you'll see that tasks.json is missing property "source" and "make".
These are just your standard BlitzMax compiler options.
Let's insert them based on what the BlitzMax bmk compiler wants, and remember to trigger auto complete to get suggestions.

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "bmx",
			"label": "My bmx task",
			"source": "${workspaceFolder}/hello_world.bmx",
			"make": "application"
		}
	]
}

Notice the funky looking ${workspaceFolder} part.
Those are called "variable substitutions" and VS Code has a bunch them.
You can find more of them here: https://code.visualstudio.com/docs/editor/variables-reference

Our task looks pretty good!
Let's run it by clicking Terminal > Run Task... and select "My bmx task".
But it's still whining about the terminal output not being scanned.
Let's add a "problemMatcher"!

All problem matchers starts with $, and extensions can provide you with more problem matchers.
The BlitzMax VS Code extension comes with the $blitzmax problem matcher.
Let's use that

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "bmx",
			"label": "My bmx task",
			"source": "${workspaceFolder}/hello_world.bmx",
			"make": "application",
			"problemMatcher": "$blitzmax"
		}
	]
}

The problem matcher will scan all the terminal output, and if it finds anything it considers a "problem" it will report on it.
This can appear as a simple warning in the "Problem" view, to a direct line jump to where there's an error in your code.

The bmx type adds many other options that you're free to explore, most of them are directly taken from the BlitzMax compiler.
Just use ctrl + space to see all of the options.
For example; "debug": false, "quick": true etc.

Task groups

Tasks can belong to either the "none", "test" or "build" group.

You don't have to worry too much about the "none" group, it's just where ungrouped tasks end up.

The "test" group is supposed to contain tasks that run specific command that is somewhat likely to fail.
For example; if you build your application using a bmx type task, you can then run a test task that starts the application with a specific set of arguments to see if your application runs into an error.
To set the group to test, all you have to do is add "group": "test".
You can also set it as your default test task by adding

"group": {
	"kind": "test",
	"isDefault": true
}

The "build" group is specifically made for when you want to build your project.
For example; the task we previously created for building our hello_world.bmx project can be set as a build task.
To set the group to build, all you have to do is add "group": "build".
You can also set it as your default build task by adding

"group": {
	"kind": "build",
	"isDefault": true
}

The default build task is special in that it's easily triggered by pressing ctrl + shift + b.
Or via Terminal > Run Build Task....
This task is also the task that the 'BlitzMax' build view uses, provided that it's of the bmx type.
Editing your default build task settings, saving, will result in the 'BlitzMax' build view updating as well.
And the other way around works as well, where changing settings in the 'BlitzMax' build view will alter the task.
Try having your tasks.json file open, with a task set as your default build task, and alter some build options in the 'BlitzMax' view.
You'll see the file being updated live.

If the tasks.json file does not exist, the 'BlitzMax' build options will use an internal task.
The internal task is also used for single files that do not belong to any project or workspace.

Can we do something useful now?

Okay, enough beating around the bush, let's create some useful task examples!
I'll introduce tasks that depends on other tasks, as well how you can quickly switch between build tasks.

Let's say we're creating a server (server.bmx) and client (client.bmx).
This would involve compiling both the server and the client, with perhaps different build options for both.
This task setup will let you to compile either one, or both at the same time using the "dependsOn" option.

{
	"version": "2.0.0",
	"tasks": [
		{
			"type": "bmx",
			"label": "Compile server",
			"source": "${workspaceFolder}/server.bmx",
			"make": "application",
			"problemMatcher": "$blitzmax",
			"apptype": "console",
			"args": ["-tcp"],
			"group": {
				"kind": "build",
				"isDefault": true
			}
		},

		{
			"type": "bmx",
			"label": "Compile client",
			"source": "${workspaceFolder}/client.bmx",
			"make": "application",
			"problemMatcher": "$blitzmax",
			"apptype": "gui",
			"args": ["-connect localhost"],
			"group": "build"
		},

		{
			"type": "bmx",
			"label": "Compile server then client",
			"make": "application",
			"source": "",
			"dependsOn": [
				"Compile server, Compile client"
			],
			"group": "build",
			"problemMatcher": "$blitzmax"
		}
	]
}

Notice that "Compile server then client" uses the "dependsOn" option, which will run the two other tasks.
The server is built as a console application, while the client is built as a gui application.

If you jump over to the 'BlitzMax' view and look at the top of the build options tree, you'll see the workspace/folder name, which in our case should be "TASK_TEST".
Beside that is the name of the task currently set as the default build task, which should be "Compile server then client".
You can quickly change the default build task by clicking Terminal > Configure Default Build Task...
Try setting the default build task to "Compile server" by clicking Terminal > Configure Default Build Task.. and selecting "Compile server".
The tasks.json file will open and set "Compile server" as your new default build task, and the 'BlitzMax' build tree will update as well, displaying "Compile server" as the current build task.
You can also hover over the task name in the 'BlitzMax' build tree and click the cog to quickly switch build task as well.

Now you have a proper setup for compiling both a server and client with different build options.
And you can easily switch between compiling the server, client, or both.

There are of course a million other examples for this, but this guide is already amazingly long, so I'll keep it short and say that tasks are worth toying with.
You could for example have a shell task upload your built application to a FTP.
You could trigger GitHub workflows via a shell task.
You could have a shell task for quickly opening up your image editing software, enter a file as the argument to have it quickly open image files you're likely to edit a lot.
You could have a shell task for creating a release for your application, by moving it to a release folder, along with all the data files required.
You can compile multiple things at once, with different build options and parameters, outputs and input.

You mentioned task templates?

In the future when you want to create a task, you don't have to write your own tasks.json file.

When you click something like Terminal > Configure Defauilt Build Task... VS Code will scan all your extensions for matching task templates for the current programming language.
The BlitzMax VS Code extension provides task templates for 'Console', 'GUI', 'Module' and 'Shared Library' tasks.
Editing a build option in the 'BlitzMax' build tree will also move the internal task into tasks.json, which you're free to edit as you like.

Remember that ctrl + space will present you with all available task options.
And hovering over any task option will show information about it.