Custom Tasks

Build, run, and clean your project.

Nova’s Tasks system allows you to write and execute scripts for building, running, and cleaning your project. Task scripts can be written in multiple scripting languages, such as Python or simple shell scripts, and can be chained together with other actions in a pipeline. Task scripts can run locally on your Mac, or on a remote server over SSH.

Tasks can be managed from the Project menu > Project Settings. You can select an existing Task configuration from the sidebar on the left, or click the + icon to create a new Task. Having multiple Tasks allows you to have different configurations for different scenarios. For your instance, you may have a “Debug” Task for building debug versions of your project, and a “Release” Task for release builds.

This article will focus on Custom Tasks, but Nova also supports two other types of Tasks - Task Templates provided by extensions, and Debug Tasks for connecting to external debugging tools.

Configuring Tasks

A Custom Task is divided into three configurable actions:

Build: Build or compile code for running or distribution.
Run: Run or execute your project.
Clean: Clean up build artifacts or temporary files.

Technically, your scripts for each action can do anything you want them to - these predefined names and icons are for your convenience. Use them in whatever way makes most sense for your particular project!

Depending on your project, you might define only one action for your Task, but any combination of Build, Run, and Clean may be defined for a given Task configuration based on your needs.

Editing Task Actions

Selecting an existing Task from Project Settings will display the interface for configuring your Task actions.

The interface for configuring a Task script.

The Where option at the top allows you to choose whether this Task’s scripts will run on your local Mac, or on a remote server. Any remote servers using the SSH protocol should appear as options in this menu.

Below that, you can switch between writing scripts for the Build, Run, or Clean actions, or configure Arguments. Select the action you want to write or edit the script for, and check Enable the Build/Run/Clean action for this Task to enable that action.

You can write your script directly in the Script field, or you can select the Path option to point Nova to an existing script file. At the top-right of the Script field, you can choose a language to write your script in. Tasks support a number of scripting languages:

Shell scripts
JavaScript
Lua
Perl
PHP
Python
Ruby
TypeScript

Some scripting languages may require you to install an interpreter separately in order to execute them. Nova will automatically look for relevant interpreters in your shell environment, but you can also manually point Nova to an interpreter’s executable from the Interpreter field.

NOTE: Task scripts in Nova run in a non-interactive shell. Tools or scripts that require user input may not work correctly.

Open Report: Choose how to view the output of your script. You can have the report open as soon as you run the Task, after the Task has finished running, only if the Task is successful or fails, or simply never open the report. You can also choose to show a progress indicator in Nova’s toolbar while a Task script is actively running.
Build Before Running: Unique to the Run action, enabling this option will always run the Build action before the Run action.

Invoking Actions

Once a Task has been configured, there are two main ways to execute a particular action:

Projects with Tasks configured will display controls in the toolbar for starting and stopping Task Actions.

Click to invoke your Build Action, and to invoke your Run Action. While a Task Action is running, you can click to stop the running Task.

On the right is a dropdown menu where you can switch Task configurations, if multiple Tasks exist for the current project. The Build and Run buttons will automatically be enabled or disabled based on whether those actions are configured for the selected Task.

Menu items for invoking Task Actions can be found in the Project menu:

⌘Command+B: Build
⌘Command+R: Run
⌘Command-⇧Shift-K: Clean
⌘Command-.: Stop (only while a Task is running)
⌃Control-0: Tasks > Choose Task (opens the Task Configuration menu in the toolbar)

These bindings can be changed in Settings > Key Bindings. These menu items can also be invoked from the Command Palette.

Outputs and Reports

Depending on the setting chosen for Open Report in your Task configuration, your Task script may display a report while running, or after completing. This allows you to see the output of any commands executed by your Task script. Reports open in a dedicated tab in the main content area.

Viewing a Task Report.

Along the top of a Report tab, you’ll find a dropdown menu where you can view previous Task Reports, as well as a button to save the report to a file.

If you chose not to automatically open a report, you can still open a report manually while a Task is running by clicking the Show Report icon in the toolbar next to the Task controls.

Note the Show Report button next to the status of the running Task.

You can also view and open Task Reports from the Reports Sidebar icon Reports Sidebar, which is not visible in the Sidebar Dock by default, but can be found in the View menu > Sidebars.

Arguments

The Arguments tab allows you to configure custom arguments and environment variables to pass to your Task’s scripts.

Arguments Passed on Launch: Passed to your Task scripts and accessible using $ syntax. Use $1 to call the first argument, $2 for the second, and so on.
Environment Variables: Set in the shell environment that Tasks run in. Both the variable name and value are manually assigned, and accessible by calling $(variable name) in your Task scripts. Can also be used to override existing environment variables used by programs or scripts you may run.

Click + to add a new argument or environment variable, or - to delete the currently selected argument.

Wildcards

In addition to simply setting static arguments, you can also use Wildcard icon Wildcards to dynamically pass information about your project or files to your Task scripts. Supported Wildcards include:

Project

Project Name: The name of the project in Nova.
Project Path: The full file path of the project’s root folder.
Project Folder Name: The name of the project’s root folder.
Branch Name: The name of the currently checked-out Git branch.

Currently Focused File

File Path: The exact file path of the currently focused file.
Relative File Path: The path of the current file relative to the project’s root folder.
File Name: The name (including extension) of the current file.
File Parent Folder Name: The name of the first ancestor folder of the current file.
File Extension: The file extension of the current file.
Line Number: The line number of the cursor in the currently focused editor.
Selected Text: The contents of any selected text in the currently focused editor.

Advanced Wildcards

Configuration Value: Pass the value for a key from the project’s .nova/Configuration.json file, useful for passing the value of a project setting to scripts.
Extension Command: Some extensions may allow you to pass commands to them. Use this Wildcard to pass a command to a supported extension. The Wildcard will be replaced with the result the extension returns.

Arguments in Action

As a simple example of how arguments can be used, say you’re writing a project in Python. Your project contains multiple Python scripts, and you want a Task that will simply run whichever Python script is currently focused in Nova’s Editor. You can pass the relative file path of the currently focused file as an argument…

Using the Relative File Path Wildcard as an Argument.

… then use that argument in your Task script to pass that filename to python3.

Passing the name of the currently focused file to Python.

Task Pipelines

Sometimes, building or running your project may be a multi-step process that can’t be contained in a single shell script. In these cases, you can use Task Pipelines to chain together multiple steps which are executed in order when running a Task Action.

To configure a Task Pipeline, expand a Task Configuration on the left in Project Settings, then select the action whose pipeline you want to edit.

An empty Task Pipeline for a Build action.

Task Pipelines appear as a series of steps in sequential order from top-to-bottom. The main script for a given Task Action must be one of those steps, but multiple additional steps can be added and ordered however you choose. Click the + icon in the top-right corner to add a step. Select a step and press Delete to delete that step (except for the action’s primary step). Click and drag steps around to reorder them.

Available steps include:

Run Script: Run an additional script as part of the pipeline, in any of the syntaxes supported by Task Scripts described above.
Run Another Task: Run a Task Action that’s part of a different Task configuration.
Play Sound: Play a sound effect.
Speak Text: Use macOS’s text-to-speech functionality to play a message.

For instance, you can add a step of running a script before Nova runs your Build script, then have Nova run a clean-up Task after building, and finally play a sound when everything is complete.

A Pipeline which runs a separate script, executes a Task action, runs a separate Task, then plays a sound effect.

Task Templates

RESULTS:

Custom Tasks