{"__v":47,"_id":"54d032c0c795960d009f4211","category":{"__v":24,"_id":"54cfba19bba1a023008741b9","pages":["54d0351994f7980d0081b848","54d03542c795960d009f4219","54d0357d94f7980d0081b84b","54d039c3f530ca0d0005396a","54d039e394f7980d0081b859","54d03a1294f7980d0081b85b","54d03a3bf530ca0d0005396e","54d03a9294f7980d0081b85e","54d03abdc795960d009f4220","54d03ade94f7980d0081b860","54d03b02f530ca0d00053970","54d03b3794f7980d0081b862","54d03b69f530ca0d00053973","54d03b8994f7980d0081b864","54d03bb1c795960d009f4222","54d8f49e6a09052100a6b60e","54ec495d7ab3172d00c01a92","54ec6f2ec0c0ba1700386fa6","54f6f3f852174719008f6168","5628ed9b48742a0d00474591","564b714fcc472d0d00da941e","564b9e65288b1a2b00b3ae7d","564ba4872cabb82100943f0d","56995b3e54d7db17000ee9e6"],"project":"54cf411f9d09bb0d00a17a1c","version":"54cf411f9d09bb0d00a17a1f","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-02T17:55:37.930Z","from_sync":false,"order":4,"slug":"running-and-debugging","title":"Running and Debugging"},"parentDoc":null,"project":"54cf411f9d09bb0d00a17a1c","user":"54cfa8c8a8a4fd0d00b7fd1c","version":{"__v":14,"_id":"54cf411f9d09bb0d00a17a1f","project":"54cf411f9d09bb0d00a17a1c","createdAt":"2015-02-02T09:19:27.656Z","releaseDate":"2015-02-02T09:19:27.656Z","categories":["54cf41209d09bb0d00a17a20","54cfb99bbba1a023008741af","54cfb9a65ff7e617002bbd7f","54cfba03bba1a023008741b6","54cfba0ebba1a023008741b8","54cfba19bba1a023008741b9","54cfba29bba1a023008741bb","54cfba345ff7e617002bbd87","54cfba3ebba1a023008741bc","54cfba473995cf0d0006f6f0","54e371b18ef7552300409bf2","54e37aa5e887c50d005ef629","555a4e9b147f91190092d137","56b0e91802f4bc0d006ce254"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-02-03T02:30:24.691Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Luckily you're not limited to the default set of Runners in Cloud9. You can simply define your own custom Runner, which is both simple and very powerful. All you need to do is create a Runner file. In this article we'll describe how to do this in just a few steps.\n\nIn the Run panel (usually at the bottom of the UI), click the 'Runner' text input and choose 'New Runner'. In the new Runner file that's now opened, you can configure your runner using a simple JSON format. We'll show a basic example below and then explain the different properties you can use.\n\n# Go Runner Example\n\nLet's start with a basic example: a runner for Go files.\n\n```\n{\n    \"cmd\": [\"go\", \"run\", \"$file\", \"$args\"],\n    \"selector\": \"source.go\",\n    \"info\": \"Your code is running :)\"\n}\n```\n\nThis runner will use \"go run\" for any file that has a \".go\" file extension. If you add it, it'll override our default Go runner.\n\nAs another example, let's save a new Node 0.11 configuration, including Harmony support. Create a new Runner, add this code, and save it as 'Node 0.11.x.run':\n\n```\n// This file overrides the built-in Node 0.11.x runner\n// For more information see http://docs.c9.io:8080/#!/api/run-method-run\n{\n  \"cmd\": [\n    \"bash\",\n    \"--login\",\n    \"-c\",\n    \"nvm use 0.11 > /dev/null; node --harmony ${debug?--nocrankshaft --nolazy --debug-brk=15454} '$file' $args\"\n  ],\n  \"debugger\": \"v8\",\n  \"debugport\": 15454,\n  \"info\": \"Your code is running at \\\\033[01;34m$url\\\\033[00m.\\n\\\\033[01;31mImportant:\\\\033[00m use \\\\033[01;32mprocess.env.PORT\\\\033[00m as the port and \\\\033[01;32mprocess.env.IP\\\\033[00m as the host in your scripts!\\n\"\n}\n```\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Alternatively, you can check 'Show Hidden Files' in your workspace directory tree (the small gear in the upper right corner), and create a new file in the '.c9/runners' folder called 'Node 0.11.x.run' with this code.\",\n  \"title\": \"Runners in Hidden Files\"\n}\n[/block]\nThat's it! Your custom Runner should be available in the Run panel.\n\n# Runner Object Properties\n\nAll of the following can be used as a key in the object in your runner file.\n\n`cmd` - An array of strings that combine to make one command that your runner will run from the terminal.\n`script` - A bash script (which can be written as array of lines for readability) your runner executes in the terminal.\n`info` - Information to be displayed in the terminal when your runner starts.\n`selector` - The type of file your runner will work with.\n`working_dir` - The directory your runner will run from.\n`debugger` - If your runner attaches to a debugger, this is which one it is e.g. xdebug, gdb, v8, etc.\n`debugport` - The port that your runner will attach to a debugger on.\n`env` - Any environment variables you'd like to make available to your runner.\n\n# Runner Variables\n---\n\nHere's a list of all the variables you can use in your runners (examples are all for a file called `/home/ubuntu/workspace/docs/Chapter1.txt`:\n\n  * `$file_path` The directory of the current file, e. g. `/home/ubuntu/workspace/docs`\n  * `$file` The full path to the current file, e. g. `/home/ubuntu/workspace/docs/Chapter1.txt`.\n  * `$args` Any arguments entered after the file name.\n  * `$file_name` The name portion of the current file, e. g., `Chapter1.txt`.\n  * `$file_extension` The extension portion of the current file, e. g. `txt`.\n  * `$file_base_name` The name only portion of the current file, e. g. `Chapter1`.\n  * `$packages` The full path to the Packages folder (should always be `~/.c9/packages`).\n  * `$project_path` The full path to the workspace's project directory (should always be `/home/ubuntu/workspace/`).\n  * `$project_name` The name of your workspace e.g. `demo-project`.\n  * `$hostname` The hostname of the workspace e.g. `demo-project-username.c9users.io`.\n  * `$hostname_path` The hostname of the workspace together with the relative path of the project file e.g. `https://demo-project-username.c9users.io/Chapter1.txt`.\n  * `$url` The full url to access the workspace e.g. `https://demo-project-username.c9users.io`.\n  * `$port` The primary port assigned to the workspace (should always be `8080`).\n  * `$ip` The ip address to run a process against in the workspace (should always be `0.0.0.0`).\n\n# Examples\n---\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Most of these runners are submitted by users and are simply for your reference. We do not specifically support any of the following runners but they can be used to learn from and work off of. Any suggestions or contributions of your personal custom runners are welcome!\",\n  \"title\": \"Suggestions Welcome\"\n}\n[/block]\n## Print runner variables\n\nThis runner simply runs `ls -la` and then prints out a ton of different variables mentioned above so you can see them in action.\n\n```\n{\n    \"cmd\" : [\"ls\", \"-la\"],\n    \"info\" : \"File path: $file_path\\nFile: $file\\nArguments: $args\\nFile name: $file_name\\nFile extension: $file_extension\\nFile base name: $file_base_name\\nPackages: $packages\\nProject path: $project_path\\nProject name: $project_name\\nHostname: $hostname\\nHostname path: $hostname_path\\nURL: $url\\nPort: $port\\nIP: $ip\\nCommand: $command\\nPython: $python\\nPython path: $python_path\",\n    \"env\" : {},\n    \"selector\" : \"source.ext\"\n}\n```\n\n## Django\nThis runner helps to run multiple Django applications in a single private workspace with virtualenv. Make sure the project path is set correctly and add cd to where you install your virtualenv.\n\n```\n{\n\t\"cmd\": [\n\t\t\"bash\",\n\t\t\"--login\",\n\t\t\"-c\",\n\t\t\"source bin/activate && cd django_root_project && python manage.py runserver $ip:$port\"\n\t],\n\t\"working_dir\": \"$project_path\",\n\t\"info\": \"Your code is running at \\\\033[01;34m$url\\\\033[00m.\\n\\\\033[01;31m\"\n}\n```\n\n## Java Runner (file)\n\nThis runner builds the Java file that is currently open and then runs it.\n```\n{\n  \"script\": [ \n    \"javac $file_name\",\n    \"java $file_base_name\"\n  ],\n  \"info\": \"Building $file_name and running $file_base_name\",\n  \"selector\": \"source.java\"\n}\n```\n\n## Java Runner (project)\n\nThis runner builds all Java files in the whole workspace and then runs them.\n```\n{\n    \"script\": [\n        \"ROOT=`pwd`\",\n        \"printf \\\"\\\\033[01;34mCompiling all files in\\\\033[00m \\\\033[01;31m$ROOT\\\\033[00m\\n\\\"\",\n        \"OUT_DIR=\\\"$([ -f .bin ] && rm -r .bin; mkdir -p .bin ; echo .bin)\\\"\",\n        \"FILES=\\\"$(find . -path './.c9*' -prune -o -print | grep '.*\\\\.java' | sed 's:^./::g' | tr '\\n' ' ')\\\"\",\n        \"MAIN_CLASS=\\\"$(echo $file | sed \\\"s:$ROOT/::g\\\" | sed 's:.java$::g' | sed 's:/:.:g')\\\"\",\n        \"COMPILED_FILES=\\\"$(javac -d $OUT_DIR $FILES)\\\"\",\n        \"java -classpath \\\"$OUT_DIR\\\" \\\"$MAIN_CLASS\\\" \\\"$args\\\"\"\n    ],\n    \"env\": {},\n    \"info\": \"\\\\033[01;34mRunning\\\\033[00m \\\\033[01;31m$file_name\\\\033[00m\\n\",\n    \"selector\": \"source.java\"\n}\n```\n\n<div style=\"text-align: center;\"><a target=\"_blank\" href=\"https://community.c9.io/t/documentation-custom-runners/1459?utm_source=docs.c9.io&utm_medium=article&utm_campaign=Docs%2BFeedback\" class=\"button info solid\">Submit feedback or questions about this page</a></div>","excerpt":"","slug":"custom-runners","type":"basic","title":"Custom Runners"}
Luckily you're not limited to the default set of Runners in Cloud9. You can simply define your own custom Runner, which is both simple and very powerful. All you need to do is create a Runner file. In this article we'll describe how to do this in just a few steps. In the Run panel (usually at the bottom of the UI), click the 'Runner' text input and choose 'New Runner'. In the new Runner file that's now opened, you can configure your runner using a simple JSON format. We'll show a basic example below and then explain the different properties you can use. # Go Runner Example Let's start with a basic example: a runner for Go files. ``` { "cmd": ["go", "run", "$file", "$args"], "selector": "source.go", "info": "Your code is running :)" } ``` This runner will use "go run" for any file that has a ".go" file extension. If you add it, it'll override our default Go runner. As another example, let's save a new Node 0.11 configuration, including Harmony support. Create a new Runner, add this code, and save it as 'Node 0.11.x.run': ``` // This file overrides the built-in Node 0.11.x runner // For more information see http://docs.c9.io:8080/#!/api/run-method-run { "cmd": [ "bash", "--login", "-c", "nvm use 0.11 > /dev/null; node --harmony ${debug?--nocrankshaft --nolazy --debug-brk=15454} '$file' $args" ], "debugger": "v8", "debugport": 15454, "info": "Your code is running at \\033[01;34m$url\\033[00m.\n\\033[01;31mImportant:\\033[00m use \\033[01;32mprocess.env.PORT\\033[00m as the port and \\033[01;32mprocess.env.IP\\033[00m as the host in your scripts!\n" } ``` [block:callout] { "type": "success", "body": "Alternatively, you can check 'Show Hidden Files' in your workspace directory tree (the small gear in the upper right corner), and create a new file in the '.c9/runners' folder called 'Node 0.11.x.run' with this code.", "title": "Runners in Hidden Files" } [/block] That's it! Your custom Runner should be available in the Run panel. # Runner Object Properties All of the following can be used as a key in the object in your runner file. `cmd` - An array of strings that combine to make one command that your runner will run from the terminal. `script` - A bash script (which can be written as array of lines for readability) your runner executes in the terminal. `info` - Information to be displayed in the terminal when your runner starts. `selector` - The type of file your runner will work with. `working_dir` - The directory your runner will run from. `debugger` - If your runner attaches to a debugger, this is which one it is e.g. xdebug, gdb, v8, etc. `debugport` - The port that your runner will attach to a debugger on. `env` - Any environment variables you'd like to make available to your runner. # Runner Variables --- Here's a list of all the variables you can use in your runners (examples are all for a file called `/home/ubuntu/workspace/docs/Chapter1.txt`: * `$file_path` The directory of the current file, e. g. `/home/ubuntu/workspace/docs` * `$file` The full path to the current file, e. g. `/home/ubuntu/workspace/docs/Chapter1.txt`. * `$args` Any arguments entered after the file name. * `$file_name` The name portion of the current file, e. g., `Chapter1.txt`. * `$file_extension` The extension portion of the current file, e. g. `txt`. * `$file_base_name` The name only portion of the current file, e. g. `Chapter1`. * `$packages` The full path to the Packages folder (should always be `~/.c9/packages`). * `$project_path` The full path to the workspace's project directory (should always be `/home/ubuntu/workspace/`). * `$project_name` The name of your workspace e.g. `demo-project`. * `$hostname` The hostname of the workspace e.g. `demo-project-username.c9users.io`. * `$hostname_path` The hostname of the workspace together with the relative path of the project file e.g. `https://demo-project-username.c9users.io/Chapter1.txt`. * `$url` The full url to access the workspace e.g. `https://demo-project-username.c9users.io`. * `$port` The primary port assigned to the workspace (should always be `8080`). * `$ip` The ip address to run a process against in the workspace (should always be `0.0.0.0`). # Examples --- [block:callout] { "type": "info", "body": "Most of these runners are submitted by users and are simply for your reference. We do not specifically support any of the following runners but they can be used to learn from and work off of. Any suggestions or contributions of your personal custom runners are welcome!", "title": "Suggestions Welcome" } [/block] ## Print runner variables This runner simply runs `ls -la` and then prints out a ton of different variables mentioned above so you can see them in action. ``` { "cmd" : ["ls", "-la"], "info" : "File path: $file_path\nFile: $file\nArguments: $args\nFile name: $file_name\nFile extension: $file_extension\nFile base name: $file_base_name\nPackages: $packages\nProject path: $project_path\nProject name: $project_name\nHostname: $hostname\nHostname path: $hostname_path\nURL: $url\nPort: $port\nIP: $ip\nCommand: $command\nPython: $python\nPython path: $python_path", "env" : {}, "selector" : "source.ext" } ``` ## Django This runner helps to run multiple Django applications in a single private workspace with virtualenv. Make sure the project path is set correctly and add cd to where you install your virtualenv. ``` { "cmd": [ "bash", "--login", "-c", "source bin/activate && cd django_root_project && python manage.py runserver $ip:$port" ], "working_dir": "$project_path", "info": "Your code is running at \\033[01;34m$url\\033[00m.\n\\033[01;31m" } ``` ## Java Runner (file) This runner builds the Java file that is currently open and then runs it. ``` { "script": [ "javac $file_name", "java $file_base_name" ], "info": "Building $file_name and running $file_base_name", "selector": "source.java" } ``` ## Java Runner (project) This runner builds all Java files in the whole workspace and then runs them. ``` { "script": [ "ROOT=`pwd`", "printf \"\\033[01;34mCompiling all files in\\033[00m \\033[01;31m$ROOT\\033[00m\n\"", "OUT_DIR=\"$([ -f .bin ] && rm -r .bin; mkdir -p .bin ; echo .bin)\"", "FILES=\"$(find . -path './.c9*' -prune -o -print | grep '.*\\.java' | sed 's:^./::g' | tr '\n' ' ')\"", "MAIN_CLASS=\"$(echo $file | sed \"s:$ROOT/::g\" | sed 's:.java$::g' | sed 's:/:.:g')\"", "COMPILED_FILES=\"$(javac -d $OUT_DIR $FILES)\"", "java -classpath \"$OUT_DIR\" \"$MAIN_CLASS\" \"$args\"" ], "env": {}, "info": "\\033[01;34mRunning\\033[00m \\033[01;31m$file_name\\033[00m\n", "selector": "source.java" } ``` <div style="text-align: center;"><a target="_blank" href="https://community.c9.io/t/documentation-custom-runners/1459?utm_source=docs.c9.io&utm_medium=article&utm_campaign=Docs%2BFeedback" class="button info solid">Submit feedback or questions about this page</a></div>