First Example: Compiling Pascal Source Code

In this section, I will explain how to create a custom task that allows for compiling Pascal source code files by invoking the Free Pascal command line compiler from VS Code. Assuming you have downloaded and installed the required software as listed in the preceding text, locate the Free Pascal folder installation on disk (usually /FPC/version number), then open the examples folder. In Visual Studio Code, open any folder containing some Pascal source code. I will use one called fcl-json.

Figure 8-6 shows how Visual Studio Code appears with Pascal source files currently opened.

The OmniPascal extension installed previously enables syntax colorization and the other common editing features. Now imagine you want to compile the source code into an executable binary by invoking the Free Pascal command line compiler. This can be accomplished by creating a custom task. Follow these steps to create a new tasks.json file and set up the custom task:

1. 1.

   Select Terminal ➤ Configure Task: When the Command Palette appears asking for a task to configure, select Create tasks.json from template (see Figure 8-7). There is no existing task to configure at this particular point, so the only thing you can do is creating a new tasks.json file.

    
2. 2.

   The Command Palette will now show the list of available task templates: MSBuild, maven, .NET Core, and Others (see Figure 8-8). Select Others to create a new task that is independent from other systems.

    

You could certainly specify the name of the file you want to compile, but using a variable is more flexible so that you can simply compile any file that is currently active in the code editor. In addition to the properties in tasks.json, variables are also discussed shortly and will be summarized in Table 8-3. Notice how IntelliSense helps you find the appropriate properties in tasks.json, as shown in Figure 8-9.

Save and close tasks.json, then open one of the Pascal source files. Now you can run the newly created build task. Select Terminal ➤ Run Task, and from the Command Palette, select the build task (see Figure 8-10).

At this point, VS Code will ask you what would you like to do to detect any problems encountered during the execution of the external program so that they can be displayed in the Problems panel. Detecting problems in the program’s output is the job of a so-called problem matcher. This is a more complex topic and will be discussed in a dedicated section. For now, select Continue without scanning the task output (see Figure 8-11).

The Free Pascal compiler will be executed in the Terminal panel, where you also see the program output as demonstrated in Figure 8-12.

If the execution succeeds, you will find a new binary file in the source code’s folder. If it fails, the compiler’s output displayed in the Terminal panel will help you understand what the problem was. Before moving to a second example, I will now explain more about default tasks, task templates, JSON properties in tasks.json, and variables.

Multiple Tasks and Default Build Tasks

Tasks.json can define multiple tasks. At the beginning of this chapter, I told you that, among the others, common tasks are build and test, but you might want to implement multiple tasks that are specific to your scenario. For example, suppose you want to use the Free Pascal compiler to build Delphi source code files.

As you can see, there is a new custom task called Delphi build in the tasks array which still invokes the Free Pascal compiler on the active file, but with the -Mdelphi option being passed as a command line argument. Now if you select Terminal ➤ Run Task again, you will see both tasks in the Command Palette, as demonstrated in Figure 8-13.

This command will automatically start the default build task, without the need of manually selecting a task every time.

Understanding tasks.json Properties and Substitution Variables

Notice how IntelliSense shows the built-in supported values for the group property (see Figure 8-14).

Other values can be omitted because we are okay with the default values seen in the preceding text.

Using variables is very common when you run a task that works at the project/folder level or against file names that you either cannot predict or that you do not want to hardcode. You can check the variables documentation for further details at https://code.visualstudio.com/docs/editor/variables-reference .

Operating System-Specific Properties

Sometimes you might need to provide task property values that are different based on the operating system. In Visual Studio Code, you can use the windows, osx, and linux properties to specify different values of a property, depending on the target.

More specifically, you will need to move the property of your interest under the operating system property and provide the desired value. In the preceding code, the command property has been moved from the higher level down to the windows and linux property nodes. All supported properties can have different values, not only command.

Reusing Existing Task Templates

In the previous example about compiling Pascal source code, you have seen how to create a custom task from scratch. However, for some particular scenarios, you can leverage existing task templates, which consists of tasks.json files already preconfigured to work with specific command and settings.

This template is very useful if you want to work with Microsoft Visual Studio solutions inside VS Code, and a more specific example is coming in the next subsection. It is worth mentioning that this template has been included thinking about C# solutions (such as web applications and Xamarin projects), but MSBuild can build any kind of solution so it can be reused for different purposes.

You will now see an example based on the MSBuild task template.

Second Example: Building a MSBuild Solution (Windows Only)

MSBuild has been the Microsoft build engine since the very first release of the .NET Framework back in 2002. It is a very powerful tool, because it can build a Visual Studio solution with no effort. So, a very nice to have feature would be the possibility of compiling your solutions and projects inside Visual Studio Code.

You can configure a task to run MSBuild.exe, the build engine used by Visual Studio. In the next example, you will see how to compile an MSBuild solution made of a Visual Basic project based on Windows Presentation Foundation (WPF), but of course all the steps apply to any .sln file and to any supported languages. If you do not have one, in Visual Studio 2017 create a blank WPF project with Visual Basic as the language. There’s no need of writing code, as I focus on the project type. Save the project, then open the project folder in VS Code.

Also, change the value of the reveal property from never to always for demonstration purposes, so that you can see the output of MSBuild in the Terminal panel. Now if you select Terminal ➤ Run Task and select the preconfigured build task, MSBuild will be started and the solution will be built, as you can see in Figure 8-15.

The preconfigured MSBuild task uses the $msCompile problem matcher to detect problems related to C# and Visual Basic in the build output, so that they can be presented in a convenient way in the user interface. Let’s spend some more words about problem matchers.

Understanding Problem Matchers

Problem matchers scan the task output text for known warning or error strings and report these inline in the editor and in the Problems panel. Visual Studio Code ships with a number of built-in problem matchers for TypeScript, JSHint, ESLint, Go, C# and Visual Basic, Lessc, and Node Sass (see https://code.visualstudio.com/docs/editor/tasks#_processing-task-output-with-problem-matchers ).

Built-in problem matchers are extremely useful, because for the aforementioned environments, VS Code can present problems that occurred at build time in the Problems panel, but it can also highlight the line of code in the code editor that caused the problem.

The owner property represents the language service, which is external in this case, but it could be, for example, cpp in the case of a C++ project. But the most important property is pattern, where you specify a regular expression (regexp) to match error strings sent by the external program. Also notice, with the help of comments, how matches are grouped by target. Building problem matchers can be tricky and it is out of the scope of this book, so I recommend you to read the official documentation available at https://code.visualstudio.com/docs/editor/tasks#_processing-task-output-with-problem-matchers .