Eclipse setup for blackberry development

These are proven-to-work steps to setup your eclipse environment for developing Blackberry applications. I hope this post will make somebody's entry into the RIM development easier.

To get started, do the following if you haven't done so:

1. Download and install Eclipse
2. Download and install BlackBerry JDE
3. Download and install Apache ant
   
4. Download RAPC ant task jar file
   

Now let's setup our eclipse environment.

1. Start your eclipse, switch to a brand-new workspace, for example: c:\RIM\workspace
2. go to Window --> Preferences --> Java --> Installed JREs, click on "Add" button.
3. In the dialog, leave the default "Standard VM" option for JRE type;
   
4. Type in a "JRE name" as you like, such as 'RIM JRE';
   
5. In "JRE Home Directory", navigate to your installed JDK home, such as 'C:\Program Files\Java\jdk1.6.0';
   
6. Leave "Default VM Arguments" blank;
   
7. Now select all the jar files in "JRE System Libraries", then click "Remove" button to remove all of them; Click "Add External JARs", navigate to you Blackberry JDE installation folder, select lib/net_rim_api.jar, such as 'C:\Program Files\Research In Motion\BlackBerry JDE 4.2.1\lib\net_rim_api.jar'.
8. Click "OK" button to add the new JRE.
9. Check the checkbox of your newly added JRE to make it the default (Optional: select this JRE, click on "Edit" button to see if the system libraries are still like you set. It happened to me a couple times that eclipse added the jars in JRE home back into the list.)

With the eclipse setup, we are ready to create our first project:

1. Goto File --> New --> Project, select "Java Project", enter Project Name "HelloWorld", Make sure in the JRE group the "RIM JRE" is selected. In the "Project Layout" group, I prefer to have src and class output into separate folders. Click "Finish" button.
   
2. Right click the project, select New --> Folder, create a folder named "lib"
3. Right click the project, select New --> Folder, create a folder named "resources"
4. Right click "lib" folder, select "import"; in the dialog, select "general" --> "file system", import the anttask-rapc-1.?.jar you downloaded. Right click the jar file and select "Build Path" --> "Add to Build Path".
5. Follow the same step to import an icon file in GIF format into "resources" folder. (other image formats work too, we use GIF for demo).
6. Create a package named "com.mycompany.sample"
7. Create a class named "HelloWorld.java" in this package and paste these code:
   

   package com.mycompany.sample;
   
   import net.rim.device.api.ui.UiApplication;
   import net.rim.device.api.ui.component.LabelField;
   import net.rim.device.api.ui.container.MainScreen;
   
   public final class HelloWorld extends UiApplication {
   
   public HelloWorld(){
   super();
   MainScreen screen = new MainScreen();
   screen.add(new LabelField("Hello world!"));
   pushScreen(screen);
   }
   public static void main(String[] args) {
   new HelloWorld().enterEventDispatcher();
   }
   }

8. Now right click on the project name and create a new file named "build.xml", copy and paste the following code and edit the JRE and RIM JDK pathes accordingly, also search and replace the simulator batch file "8800.bat" to one that exists in your JDE (this ant build script is modified based on a post in Blackberry Java Forum.)

   
   <?xml version="1.0" encoding="UTF-8"?>
   
   <project name="HelloWorld" default="buildRIM" basedir=".">
   
   <taskdef name="rim" classname="com.etaras.anttask.rapc.RAPC" classpath="lib/anttask-rapc-1.8.jar" />
   
   <property name="jdehome" value="C:\Program Files\Research In Motion\BlackBerry JDE 4.2.1" />
   <property name="javahome" value="C:\Program Files\Java\jdk1.5.0_11"></property>
   <property name="simulator" value="${jdehome}\simulator" />
   <property name="bin" value="${jdehome}\bin" />
   
   <target name="debug" depends="buildRIM">
   <copy todir="${simulator}" overwrite="true">
   <fileset dir=".">
   <include name="*.cod" />
   <include name="*.debug" />
   <include name="*.csl" />
   <include name="*.cso" />
   </fileset>
   </copy>
   <exec executable="cmd.exe" dir="${bin}" spawn="true">
   <arg value="/c" />
   <arg value="jdwp.bat" />
   </exec>
   </target>
   
   <target name="simulate" depends="deploy">
   <exec executable="cmd.exe" dir="${simulator}" spawn="true">
   <arg value="/c" />
   <arg value="8800.bat" />
   </exec>
   </target>
   
   <target name="deploy" depends="buildRIM">
   <copy todir="${simulator}" overwrite="true">
   <fileset dir=".">
   <include name="*.cod" />
   <include name="*.debug" />
   <include name="*.csl" />
   <include name="*.cso" />
   </fileset>
   </copy>
   </target>
   
   <target name="buildRIM" description="Composes RIM">
   <rim jdehome="${jdehome}" javahome="${javahome}">
   <workspace src="helloworld.jdw" build="true" update="true">
   <cldc src="helloworld.jdp"
   title="HelloWorld"
   vendor="my company"
   version="0.1"
   description="HelloWorld"
   arguments=""
   systemmodule="false"
   runonstartup="false"
   startuptier="7"
   ribbonposition="0"
   output="helloworld"
   options="-quiet"
   update="true">
   <files dir=".">
   <include name="**/*.java" />
   <include name="resources/**/*.*" />
   </files>
   <icons dir=".">
   <include name="resources/**/*.png" />
   <include name="resources/**/*.gif" />
   </icons>
   </cldc>
   </workspace>
   </rim>
   </target>
   
   </project>
   

   
   
9. Open a DOS window, change to the directory where you have your build.xml file, type "ant simulate", this task will build the project, deploy it and start the simulator.
10. Look for the logo you picked for your HelloWorld app and open it, you should see a blank screen displaying "Hello World!". How exciting!

I will write down my experience of debugging applications inside eclipse in the next couple of days.