Monday, January 14, 2013

Integrating Dart into Eclipse (and your Java Eclipse project)

The goal: Java Tomcat
serving a Dart app
The Dart Editor is awesome - no doubt about that, with its static analysis, code refactoring and debugger integration with Dartium (the Chromium + Dart VM).  Dart is capable of running on both the client (either as native Dart, or as JavaScript), and on the server (in the server-side Dart virtual machine).  Sometimes, however, you might need to keep your existing server-side infrastructure, such as your enterprise Java containers such as websphere or jboss.

As a developer, it would be great to be able to use a single tool that lets you to edit client-side Dart code along with your server-side Java code.  Fortunately, the Dart Editor is built on the Eclipse RCP platform, and the editor guys have converted the Dart Editor into an Eclipse plugin.

The Dart Editor is designed to be a lightweight editor, rather than a fully featured IDE, so if you want extra plugins, such as git integration, then you can also use the Dart Editor plugin with a standard version of eclipse, and simply install your extra plugins into eclipse.

Prefer IntelliJ to Eclipse?  Then check out the JetBrains blog post about integrating the Dart SDK and with their tools.
In this blog post, you will learn how to install the Dart Editor into Eclipse, add Dartium and setup a Dart project.  Then you'll convert that project into a Java + Maven project and get it running with Java in Tomcat.

(Perhaps this blog post is rather timely, given the first sight of java2dart - discussion here)

At a high level, the steps are as follows.  I'll take you through the steps using screenshots, as some of the eclipse project config needs to be done in the correct order.

High Level overview...

  • Download Eclipse
  • Install the Dart Editor
  • Unzip Dartium into Eclipse install
  • Create a Dart project
    • Stop here if you just want a Dart Editor with extra plugin options
  • Convert it to a Maven project
  • Convert project to a faceted form
  • Add Java and Dynamic Web Module facets
  • Add local Tomcat webserver and add the project to Tomcat
  • Configure the deployment assembly
  • Start tomcat
  • Browse to your Dart + Java powered website.

Let's follow the steps...

1. Download, unzip and run Eclipse

We'll start with a completely fresh copy if eclipse, to which we'll add various add-ons and plugins.  Visit and download Eclipse IDE for Java EE Developers.

Download Eclipse IDE for Java EE Developers from
Once you've downloaded Eclipse, unzip it.  For the purposes of this discussion, I'm going to unzip it into c:\work\dart_eclipse, so that you have a folder structure as follows:
Run eclipse, and put your workspace somewhere.  I like to keep mine with the eclipse, so I'm going to set my workspace to c:\work\dart_eclipse\workspace.

2. Install the Dart Editor Plugin

Once you have Eclipse running, the next step is to install the Dart Editor plugin into eclipse.  This plugin is build from exactly the same source as the real Dart Editor.  Go to Help > Install New Software, and enter the Dart Editor eclipse update url: and hit Enter.  Select the Dart Editor and child options from the items that appear in the center section.
Add the Dart Editor plugin to Eclipse
Hit next a few times and finish, and after a restart of eclipse, the Dart Editor will be installed, along with a new "Dart" perspective.
This only installs the Dart Editor, and not Dartium - you need to "install" this separately.  

3. Install Dartium

Dartium is the Chromium browser with the Dart VM installed. You can get the Dartium-only download (ie, the one that's not bundled with the stand-alone Dart Editor) from
Open the zip file, and you should rename the dartium-xxx-yyy folder in the zip file to become chromium, which is placed in the same place as the eclipse binary (in my install, this becomes c:\work\dart_eclipse\eclipse\chromium )
Rename the dartium folder to chromium, and place in the eclipse folder
This makes Dartium available to be launched by the Dart Editor Plugin.

4. Create a Dart Project

Now that you have Eclipse, the Dart Editor Plugin, and Dartium, let's create a Dart project to check that everything's working ok.  My project is going to be called tryout_dart.  Use the File > New > Other... menu option to bring up the new project wizard, where you can find the Dart node to select Dart Project (if you're in the Dart perspective, you can skip this step, and select New > Dart Project from the menu).
Use the new project wizard to create a Dart Project
Once you click Next, you'll see the same new project wizard that you get in the stand-alone Dart editor.  (The actual wizard UI is changing slightly from the screenshot below as more project types get added)
The Create Dart Project wizard is the same as in the stand-alone editor
Enter a project name (such as tryout_dart), and click Finish.

Now that you have a Dart project, you can run it, using all the usual tools available within the stand-alone Dart editor.  Use the Launch button to see the various launch options, and select Dartium Launch to check that Dartium is in the correct place.
Run Dartium from the launch icon

You can also generate the JavaScript version of your app by right-clicking the project, and selecting Dart > Generate JavaScript from the popup menu.
Generate JavaScript  from the Dart submenu

Checkpoint: So far, you've got a version of the normal Dart Editor, but running as a real eclipse.  This means that you can do things like add other plugins (git / svn plugins anyone?) 

If, however, you want to use Java to power the server-side of your Dart project, then read-on.  

5. Convert the project to a Maven project

At this point, install Maven Integration for Eclipse (in the same manner that you installed the Dart Plugin earlier) - the Install Url for the Install New Software... menu option is:

Again, you click next a few times and restart to get the maven plugin installed.

Currently, our project only has a Dart Builder, and has a project structure as shown below:
Dart-only project structure

We need to change this so that eclipse identifies the project both as a Dart and a Java Dynamic Web Project.  In order to achieve this, and maintain a consistent project structure, we're going to convert the project to a Maven project (which uses a convention based project layout).  When we convert to a maven project structure, we'll end up with the project structure shown below:
New Maven project structure (note the additional "target" subfolder and "JRE System Library"

With the Maven plugin installed, right click the project, and select Configure > Convert to Maven Project.  Make sure you change the packaging from jar to war.

Convert to Maven project.  Change jar to war.
Click finish, and the project structure will be altered, and a pom.xml file (containing the Maven project config) is created.

6. Convert to a Faceted project

Now that the project is a Java project as well as a Dart project (which you can see by R/click project > properties > Builders, shown below), we need to convert the project to a Dynamic Web project (so that we can add it to the Tomcat application server).

Project now has Java, Dart and Maven builders
Right click the project, select properties, and select Project Facets.  Click on "convert to faceted form" - which will bring up a list of options shown below.  

Convert to faceted form

Select "Dynamic Web Model" and "2.5" and then click "Further configuration available..." - in the box that pops up, change the Content Directory setting from  WebContent to /src/main/webapp.

Change the Content Directory in further configuration
Now that you've converted the project to a Dynamic Web Project, the folder structure should similar to that shown below:
Dynamic web project

7. Add Tomcat app server

The next step is to add the Tomcat app server.  I'm going to use Tomcat 6 (because that's what I already have unzipped on my machine) - You can download it here:

Show the servers tab, either from Window > Servers, or clicking it if it's already open, and click New Server Wizard...
New server wizard...
Find Apache Tomcat v6.0 in the list, and click Next... which brings up the following window.  I recommend downloading and unzipping Tomcat somewhere first.  Then all you need to do is to specify the Tomcat installation directory path.

Specify tomcat installation directory
Click Next, and you'll get a view showing the available apps you can add to Tomcat.  tryout_dart should be on the left hand, "available" side - add it to move it to the "configured" side.
Click Finish, and your app has been added to tomcat.

8. Add Dart to the deployment assembly

Now, your dynamic web project knows about the Java files, but not the Dart files.  You need to add them to the Web Deployment Assembly.  I'm going to assume that you're serving your Dart files from a url folder named dart/ (which maps to the web/ folder in your Dart project).  Right click the project again, select properties, and click "Deployment Assembly". Click "Add..." to add a Folder directive, and select the /web folder.  Once the "Add..." dialog has closed, edit the right hand column against your /web entry to read /dart (shown below)

Add Dart project's web folder to Tomcat's hosted output

9. Run your Dart app, hosted in Tomcat.

Your Dart + Java app is ready to go (ok, we've not actually written any Java, but I'm guessing you already know how to do that bit).  Go to the Servers tab, right-click Tomcat, and click Start.  Tomcat will start serving your app.
Start Tomcat to serve your Java and Dart app.

Launch Dartium (either from the command line by running chromium.exe, or using the Launch menu (which launches the Dart app using the Dart plugin's own internal web server), and browse to: http://localhost:8080/tryout_dart/  this will take you to tomcat's Hello World default page.
Tomcat's default "hello world"

Now browse to http://localhost:8080/tryout_dart/dart/tryout_dart.html - and you will see your Dart app running, served by Tomcat.  

Tomcat serving the Dart app


I'm sure you'll have issues with regards to the combination Tomcat / Maven / Project Structure / Publishing (I know I do, in almost every Eclipse Java project I end up working on), but hopefully this should be able to get you started.  Whether you simply use the Dart Plugin for Eclipse to get more addons, or keep the Dart and Java projects separate but in the same workspace, I hope this post has been of some use to show how Dart and Java can co-exist.

(If you're interested in going further, then there is a dart-maven project on github that might be worth taking a look at).


  1. Thanks Chris. I am very much looking forward to your next book on Dart.

  2. Just what I was looking for, thanks !!!

  3. Thank you for this! Very helpful!