{"_id":"54fa1dcff63cf9210041c4c0","parentDoc":null,"user":"54cfa8e1a8a4fd0d00b7fd1d","project":"54d53c7b23010a0d001aca0c","category":{"_id":"54fa1d3fe7a0ba2f00306309","project":"54d53c7b23010a0d001aca0c","version":"54d5635532d98b0d00384afb","__v":5,"pages":["54fa1d54e7a0ba2f0030630c","54fa1d5de7a0ba2f0030630e","54fa1d65961fea210092064f","54fa1dcff63cf9210041c4c0","551f404b6886f8230055f02f"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-06T21:33:51.375Z","from_sync":false,"order":6,"slug":"runners-debuggers","title":"Runners & Debuggers"},"version":{"_id":"54d5635532d98b0d00384afb","project":"54d53c7b23010a0d001aca0c","__v":10,"forked_from":"54d53c7c23010a0d001aca0f","createdAt":"2015-02-07T00:59:01.934Z","releaseDate":"2015-02-07T00:59:01.934Z","categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"__v":28,"updates":["54fdcfa1762e280d00225726"],"next":{"pages":[],"description":""},"createdAt":"2015-03-06T21:36:15.644Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"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. \n\nRunners 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.\n\n# Creating a New Runner\n\nYou'll want to include one or more runners in your package when you are adding support for a new runtime or a new debugger.\n\nCreate a new runner via the menu `Run / Run With / New Runner` or copy the following template.\n\n```\n{\n    \"cmd\": [\"ls\", \"$file\", \"$args\"],\n    \"info\": \"Started $project_path$file_name\",\n    \"env\": {},\n    \"selector\": \"source.ext\"\n}\n```\n\nThe `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`.\n\nThe `selector` property is a regular expression used by Cloud9 to identify the filenames that apply to that runner.\n\nThese are the supported variables.\n[block:html]\n{\n  \"html\": \"<table>\\n<tr><th>Variable</th><th>               Description</th></tr>\\n<tr><td>$file_path</td><td>           The directory of the current file, e.g. /home/ubuntu.</td></tr>\\n<tr><td>$file</td><td>                The full path to the current file, e.g. /home/ubuntu/server.js.</td></tr>\\n<tr><td>$args</td><td>                Any arguments entered after the file name.</td></tr>\\n<tr><td>$file_name</td><td>           The name portion of the current file, e.g. server.js.</td></tr>\\n<tr><td>$file_extension</td><td>      The extension portion of the current file, e.g. js.</td></tr>\\n<tr><td>$file_base_name</td><td>      The name only portion of the current file, e.g. server.</td></tr>\\n<tr><td>$packages</td><td>            The full path to the Packages folder.</td></tr>\\n<tr><td>$project</td><td>             The full path to the current project file.</td></tr>\\n<tr><td>$project_path</td><td>        The directory of the current project file.</td></tr>\\n<tr><td>$project_name</td><td>        The name portion of the current project file.</td></tr>\\n<tr><td>$project_extension</td><td>   The extension portion of the current project file.</td></tr>\\n<tr><td>$project_base_name</td><td>   The name only portion of the current project file.</td></tr>\\n<tr><td>$hostname</td><td>            The hostname of the workspace.</td></tr>\\n<tr><td>$hostname_path</td><td>       The hostname of the workspace together with the relative path of the project file.</td></tr>\\n<tr><td>$url</td><td>                 The full url to access the workspace.</td></tr>\\n<tr><td>$port</td><td>                The port assigned to the workspace.</td></tr>\\n<tr><td>$ip</td><td>                  The ip address to run a process against in the workspace.</td></tr>\\n</table>\"\n}\n[/block]\nThe following declarations can be used to add defaults or regexp\nreplacements to the these variables:\n\n    ${debug?--debug}\n\nThis will emit --debug if the debug option is set to true\n\n    ${project_name:Default}\n\nThis will emit the name of the current project if there is one, otherwise Default.\n\n    ${file/\\.php/\\.txt/}\n\nThis will emit the full path of the current file, replacing .php with .txt.\n\nPlease check out the [reference guide](https://docs.c9.io/api/#!/api/run-method-run) for more information on each of the properties that are accepted for runners.\n\n# Add a Debugger to a Runner\n\nOf 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`.\n\n```\n{\n    \"cmd\": [\n        \"node\",\n        \"${debug?--nocrankshaft}\",\n        \"${debug?--nolazy}\",\n        \"${debug?`node --version | grep -vqE \\\"v0\\\\..\\\\.\\\" && echo --nodead_code_elimination`}\",\n        \"${debug?--debug-brk=15454}\",\n        \"$file\",\n        \"$args\"\n    ],\n    \"debugger\": \"v8\",\n    \"debugport\": 15454,\n    \"selector\": \"source.js\"\n}\n```\n\nThe `$(debug?` parts of the command will only be added when starting the runner with the debugger enabled.","excerpt":"","slug":"runners","type":"basic","title":"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. [block:html] { "html": "<table>\n<tr><th>Variable</th><th> Description</th></tr>\n<tr><td>$file_path</td><td> The directory of the current file, e.g. /home/ubuntu.</td></tr>\n<tr><td>$file</td><td> The full path to the current file, e.g. /home/ubuntu/server.js.</td></tr>\n<tr><td>$args</td><td> Any arguments entered after the file name.</td></tr>\n<tr><td>$file_name</td><td> The name portion of the current file, e.g. server.js.</td></tr>\n<tr><td>$file_extension</td><td> The extension portion of the current file, e.g. js.</td></tr>\n<tr><td>$file_base_name</td><td> The name only portion of the current file, e.g. server.</td></tr>\n<tr><td>$packages</td><td> The full path to the Packages folder.</td></tr>\n<tr><td>$project</td><td> The full path to the current project file.</td></tr>\n<tr><td>$project_path</td><td> The directory of the current project file.</td></tr>\n<tr><td>$project_name</td><td> The name portion of the current project file.</td></tr>\n<tr><td>$project_extension</td><td> The extension portion of the current project file.</td></tr>\n<tr><td>$project_base_name</td><td> The name only portion of the current project file.</td></tr>\n<tr><td>$hostname</td><td> The hostname of the workspace.</td></tr>\n<tr><td>$hostname_path</td><td> The hostname of the workspace together with the relative path of the project file.</td></tr>\n<tr><td>$url</td><td> The full url to access the workspace.</td></tr>\n<tr><td>$port</td><td> The port assigned to the workspace.</td></tr>\n<tr><td>$ip</td><td> The ip address to run a process against in the workspace.</td></tr>\n</table>" } [/block] 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](https://docs.c9.io/api/#!/api/run-method-run) 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.