Advertisement

Quick Tip: Configuring Sublime Text 2 for Dart Coding

by
Student iconAre you a student? Get a yearly Tuts+ subscription for $45 →

Sublime Text 2 is a powerful text editor, popular due to its cross-platform availability and its knack for leveraging pre-existing TextMate capabilities. Combine Sublime Text 2 with Google's new Dart language, and power coders can be very happy.


Update: New Video Guide

Editor's Note: Since this article was first published, it has become out of date. There is now a much better workflow for using Dart in Sublime Text 2, which Timothy Armstrong explains in this video:


The original article is left unedited below.


Prerequisites

In order for this to go quickly, I'll assume that you have some foundational knowledge. You should be familiar with the following for this tip:

  • A working knowledge of Sublime Text 2 packages. Most of this tip centers on the steps required to build our own Dart package, but if you've never used a snippet before you might want to back up for a second and go learn more about Sublime Text first.
  • A working knowledge of Dart will also help. We won't really be coding any Dart in this tip, but having a few Dart files around with which to test things will help greatly.
  • We'll be checking code out of a Subversion repository, and while I'll feed you the command to use, hopefully this isn't your first time using Subversion.
  • Finally, a general knowledge of your particular OS is in order. We'll need to do a small amount of configuration and if you're comfortable, say, modifying a .bash_profile file via the Terminal, then you'll be fine.

If you need some prior reading material, I refer you to the following:


Step 1: Install Dart Editor

We won't really be using the Dart Editor (the point of this tutorial is to use Sublime Text for Dart development, after all), but the download includes the Dart SDK, which is really what we're after. Even if you're a hardcore Sublime Text 2 fanatic, it's still not a terrible idea to have the "official" Dart Editor installed and handy.

On the official Dart site, you can download the Dart Editor from the following link:

http://www.dartlang.org/docs/getting-started/editor/

Under "Step 1" of that page, you'll find a link to a ZIP file containing the Dart Editors. It's around 70-100 MB, depending on your OS, so it's not a terribly heavy download. But get it started!

The Dart Editor is based on Eclipse, so if you've used that you'll be right at home with the Dart Editor. I won't be getting into details on using it in this tutorial, but feel free to play around with it. The Activetuts+ introductory Dart tutorial (currently exclusively available through Facebook) takes you through the basic usage of the Dart Editor.

Note that if you don't want to install the Dart Editor, you can download just the Dark SDK for your OS at this URL (it's only 2 or 3 MB):

http://www.dartlang.org/docs/getting-started/sdk/index.html


Step 2: If You Have 64-Bit Linux

If you don't have a 64-bit Linux installation, you can skip this step. (Yep, that includes you, Windows and Mac users; scroll down for your instructions.)

If you are on a 64-bit Linux installation, you'll need to install a 32-bit library in order to run the Dart compiler, even if you've downloaded the 64-bit Dart Editor. I'm not a Linux guru by any stretch, but this worked for me, on my Ubuntu 11 installation.

Go to the Software Center and search for "lib32stdc++6" or "GNU Standard C++ Library 32 bit". Install it. You can continue on with the next few steps while it installs - just be sure this library has successfully installed before attempting to run the build system.

Install this library if you're running 64-bit Linux

Step 3: Download Google's Dart TextMate Language File

The TextMate language file is hosted on Google Code here (web-based view into the repository).

This is actually part of a larger TextMate bundle (but not that much larger), but we're only interested in the language grammar.

Before we grab that file, create a location for it to live on your system. You'll need to create a folder named Dart in the following location, depending on your OS:

  • Mac OS: ~/Library/Application Support/Sublime Text 2/Packages/Dart
  • Windows 7: C:\Users\Administrator\AppData\Roaming\Sublime Text 2\Packages\Dart
  • Linux: ~/.config/sublime-text-2/Packages/Dart

Then open up your command line interface and navigate to inside of that newly-created Dart folder.

Subversion doesn't make it easy to checkout a single file, but we can export a single file. Enter this command:

svn export http://dart.googlecode.com/svn/branches/bleeding_edge/dart/tools/utils/textmate/Dart.tmbundle/Syntaxes/Dart.tmLanguage

After a moment you should have the Dart.tmLanguage file in your Dart folder.

Go ahead and try it out (you may need to restart Sublime Text). Open up a Dart file and check out the colorful syntax:

A simple Dart file in Sublime Text 2, showing off syntax highlighting
A simple Dart file in Sublime Text 2, showing off syntax highlighting

Step 4: Locate your frogc Executable

frogc is the Dart-to-JavaScript compiler. It's a command line tool, but it's thankfully easy to use. We'll be using it in a Sublime Build System later to turn our Dart file(s) into JavaScript, so we don't even need to use it on the command line anyway.

To make the Build System, we need the path to our frogc executable. This was downloaded with the Dart SDK (which you either downloaded with the Dart Editor or by itself). It will be located at dart-sdk/bin/frogc. "dart-sdk" will either be where you downloaded and unzipped the SDK by itself, or nested just inside the dart folder which also contains the Dart Editor application, which will be where you placed it.

We need a command-line-compatible path to frogc. On Mac OS, you can do this:

Open up a Terminal window and drag frogc into it. The window will contain the text of the path of the file you dropped.

For Windows:

Click in the address bar of the window. It should turn into a plain text path for the folder, which you can then copy. You'll need to add "\frogc.bat" at the end to get the path to frogc, not just the bin folder.

If you're on Linux, you probably already know how to do this.

Make sure the path is absolute, and readily available. Place it on your clipboard or in a scratch text file for the next step.


Step 5: Create a Dart Build System to Compile JavaScript

To make this language package really useful, we should set up a Build System, which lets us run files through a shell build command.

In Sublime Text, choose the Tools > Build System > New Build System... menu. You'll be presented with a new file with the following default contents:

{
    "cmd": ["make"]
}

This is just a JSON object that describes a very basic build command. We'll add much more to this to make it useful for Dart development.

With that path you determined in the last step readily available, we can edit our sublime-build file.

If you're on Mac or Linux, change the contents of the file to:

{
    "cmd": ["/Applications/dart/dart-sdk/bin/frogc", "$file"],
    "file_regex": "^(.+\\.dart):(\\d+):(\\d+):.+\\[0m(.+)$",
    "selector": "source.dart"
}

The above is what I have on my Mac system. Where it says /Applications/dart/dart-sdk/bin/frogc, add in your own frogc path.

If you're on Windows, the file will look rather similar, but you should change the "cmd" line to:

{
    "cmd": ["cmd", "/C", "C:\\insert path here\\frogc.bat", "$file"],
    "file_regex": "^(.+\\.dart):(\\d+):(\\d+):.+\\[0m(.+)$",
    "selector": "source.dart"
}

To briefly explain what this does, the cmd property is basically just what to run on the command line. frogc is simple to use: just invoke the command and feed it a file. The $file part of that line is a variable that gets expanded automatically to the page of the current file.

On Windows, things are a little funkier by default (at least in this scenario; that's not a dig at Microsoft, I swear!). What we have will run the Windows command line (cmd) with the "don't keep the terminal window up" parameter (/C, though even the "keep the terminal window up" /K parameter doesn't show it either), and run frogc.bat, passing it the full file path. This is the quick way to get it working, but does seem to produce errors in the current build. This is probably a temporary problem, as at the time of this writing these errors are produced with the standard SDK and not the latest SDK. See the next step for an alternate route.

The file_regex line is for error reporting purposes. If a line in the output of the command matches this regular expression pattern, it's recognized as an error and pressing F4 will highlight them for you in the output panel.

Unfortunately frogc uses text-styling codes to make parts of the error message a different color and/or bold. When piped into Sublime Text, these style codes are presented as regular text, so the output can be a little hard to read, with [0m and similar codes peppered amongst the human-readable text. I'm not aware of any way around this, sadly.

The final line, selector, specifies the scope in which this Build System should take place. With this set to source.dart, Dart files should automatically choose this Build System. Sublime Text 2 knows that a ".dart" file is a, well, a Dart file thanks to the language grammar we installed.

Save this file as Dart-frogc.sublime-build in [Sublime Data]/Packages/User/Dart/


Optional Power-User Step for Windows

To avoid the aforementioned errors on Windows, and also make your build system fit more in line with the Mac and Linux versions, we can add the dart-sdk bin folder to the Windows environment, so that Sublime Text knows to look there for frogc.

To add the path, click Start, then right-click Computer, and select Properties. (Alternatively: Control Panel > System and Security > System.) Click "Advanced system settings", then on "Environment Variables."

Now, find the "path" variable, in either User Variables or System Variables (it works with either). If it doesn't exist, you can click New to create it, but if it does exist, then clicking New will overwrite it, so be careful.

Append the correct path to the end of what's already there, using a semicolon to separate it from everything else. No need to escape slashes or replace spaces with underscores or anything like that. Mine looks like:

C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Users\Administrator\Downloads\dart-win32-latest\dart-sdk\bin

(Scroll the above box to the right.)

That'll let you run frogc c:\whatever\source.dart from the command window, but it still won't work within Sublime Text 2. For some reason, ST2 on Windows requires you to specify the file extension in your build system file, like so:

"cmd": ["frogc.bat", "$file"]

At this point, you should have a usable build system on Windows that's less likely to break.


Step 6: Using the Build System

Go ahead and try our new Build System out. Open up a Dart file, and press F7 or Control-B (on the Mac, Command-B). "B" for Build.

You should see the output panel open up at the bottom, and if the Dart is error-free, you'll just see [Finished].

The Build System is successful

If you have errors, you'll get much more complex output. For example:

The Build System showing errors

When this happens, press F4 to move forward through the various lines of error, and Shift-F4 to move backward. The error line will highlight in the output panel, and your cursor will be placed at the line and column identified by the error.

The Build System highlighting an error

Step 7: Start Building Snippets

There are potentially many useful snippets to be added to a Dart bundle. Let me get you started by adding a snippet that creates a new method.

From the Sublime Text menu, choose Tools > New Snippet... You'll again be presented with a default file, this one in XML format. Change its contents to:

<snippet>
    <content><![CDATA[
${1:void} ${2:methodName}(${3:arguments}) {
    $0${1/void|(.+)/(?1:\n\treturn null;)/}
}
]]></content>
    <tabTrigger>method</tabTrigger>
    <scope>source.dart</scope>
</snippet>

Feel free to change the contents of the <tabTrigger> node from method to something else that you'll find more useful. This is what you type before pressing Tab in order to get the snippet.

Save the file as method.sublime-snippet (the extension is crucial; the base name is what your snippet will show up as in the menus), in the following location relative to your Sublime Text 2 Packages folder:

/Dart/method.sublime-snippet

You should already have the "Dart" folder from the installation of the language grammar file.

Now try out your new snippet (you may need to restart Sublime Text, but I think this is no longer an issue).

In a Dart file, type "method" (or whatever you specified, if you forged your own tab trigger), press Tab, and watch it expand. You can tab through the various stops, starting at the return type, then to the method name, and finally in between the parentheses if you want to add arguments. The last tab will drop you at the first line of the method.

The cool part is that if you change the return type from void, you get an automatic return null statement at the end of your method body. Naturally you'll want to adapt this to your needs, but hopefully it's a feature that saves a little typing. The magic happens in the unwieldy second line of the snippet; if you've never seen this before, then it's somewhat difficult to explain concisely, but it looks at the contents of the first tab stop (the return type) and if it's anything other than "void", it adds the return null. It might make sense if you've ever used Regular Expressions, particularly with the substitution syntax of /pattern/substitute/ found in Perl.

The field's wide open for the creation of time-saving Dart snippets. Feel free to post your snippets in the comments.


That's All

And there you have it; those of use who prefer a certain text editor over anything else can continue to do so, even with this new Dart language. Thanks for reading, and I hope you learned something about Sublime Text 2's extensibility along the way.

Advertisement