Runners

Runners are small JSON files that describe how to run files of a certain type. These runners can also tell Cloud9 which debugger to use and how to provide relevant information to the user who starts the runner. When a user hits the run button in Cloud9 it will use the filename to determine which runner to choose and use that runner to run that file. Users can use the run menu to select a runner of choice to run the current file.

Runners are useful to run specific files but occasionally it is useful to specify a configuration on a project level. Run configurations are useful for this, which can combine a runner with a filename, command line options, environment variables, and the current working directory. A user can specify a default run configuration for the workspace. If the default run config is set, the run button will become a run project button.

Creating a New Runner

You'll want to include one or more runners in your package when you are adding support for a new runtime or a new debugger.

Create a new runner via the menu Run / Run With / New Runner or copy the following template.

{
    "cmd": ["ls", "$file", "$args"],
    "info": "Started $project_path$file_name",
    "env": {},
    "selector": "source.ext"
}

The cmd property takes an array of command line arguments and replaces any of the accepted variables to build a command that is executed through bash. The command is run with any environment variables set in env.

The selector property is a regular expression used by Cloud9 to identify the filenames that apply to that runner.

These are the supported variables.

Variable	Description
$file_path	The directory of the current file, e.g. /home/ubuntu.
$file	The full path to the current file, e.g. /home/ubuntu/server.js.
$args	Any arguments entered after the file name.
$file_name	The name portion of the current file, e.g. server.js.
$file_extension	The extension portion of the current file, e.g. js.
$file_base_name	The name only portion of the current file, e.g. server.
$packages	The full path to the Packages folder.
$project	The full path to the current project file.
$project_path	The directory of the current project file.
$project_name	The name portion of the current project file.
$project_extension	The extension portion of the current project file.
$project_base_name	The name only portion of the current project file.
$hostname	The hostname of the workspace.
$hostname_path	The hostname of the workspace together with the relative path of the project file.
$url	The full url to access the workspace.
$port	The port assigned to the workspace.
$ip	The ip address to run a process against in the workspace.

The following declarations can be used to add defaults or regexp
replacements to the these variables:

${debug?--debug}

This will emit --debug if the debug option is set to true

${project_name:Default}

This will emit the name of the current project if there is one, otherwise Default.

${file/\.php/\.txt/}

This will emit the full path of the current file, replacing .php with .txt.

Please check out the reference guide for more information on each of the properties that are accepted for runners.

Add a Debugger to a Runner

Of special interest are the debugger and debugport properties. These are used to tell Cloud9 which debugger to use to debug the running process and on which port to connect to. The following example shows the Node.js runner which is configured to have the v8 debugger connect to port 15454.

{
    "cmd": [
        "node",
        "${debug?--nocrankshaft}",
        "${debug?--nolazy}",
        "${debug?`node --version | grep -vqE \"v0\\..\\.\" && echo --nodead_code_elimination`}",
        "${debug?--debug-brk=15454}",
        "$file",
        "$args"
    ],
    "debugger": "v8",
    "debugport": 15454,
    "selector": "source.js"
}

The $(debug? parts of the command will only be added when starting the runner with the debugger enabled.