ProjectWonderlandEclipseHowTo

Getting Wonderland to run in Eclipse can be somewhat painful but worth it, since it gives access to all the nice features of this IDE (code auto-completion, error tracing, debugging, etc.). The procedure is as follows:

1) Check out the project as a "Java project" from dev.java.net.

1. Select "File" --> "Import"
   
2. Select the "CVS" dropdown
   
3. Select "Projects from CVS"
   
4. Select "Next"

You are presented with the "Define the location and protocol required to connect with an existing CVS repository." screen

1. In the "Host" field, input "cvs.dev.java.net"
   
2. In the "Repository path" field, input "/cvs"
   
3. In the "User" field, input your dev.java.net username
   
4. In the "Password field, input your password
   
5. In the "Connection type" field, select "pserver" from the drop-down menu
   
6. Activate the "Save password" check box
   
7. Select "Next"

You are presented with the "Select the module to be checked out from CVS" screen

1. Activate the "Use specified module name:" radio button and input "lg3d-wonderland" in the corresponding field
   
2. Select "Next"

You are presented with the "Select the method of check out" screen

1. Activate the "Check out as a project in the workspace" radio button and ensure that the project name is "lg3d-wonderland" and that the "Checkout subfolders" checkbox is activated
   
2. Select "Finish"

Note: If you have already checked out the project and it's not recognized as a Java project, you can shut down eclipse, open the .project file from your favorite text editor, and add the following tags:

   <natures>
      <nature>org.eclipse.jdt.core.javanature</nature>
   </natures>

From now on we will assume all the project files were downloaded to {wonderland-source}.

Note: The default install location on Ubuntu 8.04 is /home/username/workspace/lg3d-wonderland (where username is your local user ID).

2) From a terminal window, cd {wonderland-source} and run "ant jar-all". Among other things this will create a set of platform-specific jars in {wonderland-source}/ext/{platform-name}/jars that we need below.

3) Now you need to tell Eclipse about sources and packages:

• Right-click on the project folder, select Build Path... Configure Build Path...
• In the "Source" tab, remove whatever is there and select "Add folder..." Choose {wonderland-source}/src/classes and {wonderland-source}/modules/extracells/src/classes
• In the "Libraries" tab, select "Add JARs..." Then select all the jars you can see in the following directories:
  • ext/voicebridge
  • ext/bridgemonitor
  • ext/{platform-name}/jars
  • ext/common
  • ext/sgs/darkstar/lib

At this point you should already benefit from syntax checking and code auto-completion. Verify this, for instance by opening a java file in src/classes and choosing "Open declaration" on a method or class name. If Eclipse complains you have most likely forgotten a jar or two - make sure you have them all and try again.

Note Some of you might be getting some errors in the console on the following includes:

1. import com.sun.gi.comm.routing.ChannelID;
2. import com.sun.gi.comm.users.client.ClientChannel;
3. import com.sun.gi.comm.users.client.ClientChannelListener;

These will be occurring in the following files:

1. org/jdesktop/lg3d/wonderland/darkstar/util/io/ChannelInputStream.java
2. org/jdesktop/lg3d/wonderland/darkstar/util/io/ChannelOutputStream.java

According to this thread:

1. http://forums.java.net/jive/message.jspa?messageID=232839

These files are excluded in the ant build, but the default eclipse build doesn't have them excluded. In order to exclude these two files manually in eclipse do the following:

• Right-click the project
• Select "Build Path"
• Select "Configure Build Path"
• On the "Source" folder, expand the "lg3d-wonderland/src/classes" folder
• Double click on the "Excluded" section
• Under the Exclusion patterns window click the "Add" button
• add the following exclusion pattern
  • org/jdesktop/lg3d/wonderland/darkstar/utils/io/*.java

This should remove any errors you might be receiving

4) To be able to run the server and client from within eclipse we need to tell Eclipse about Ant targets. Choose the "Run" menu and then "Open external tools dialog." Double-click "Ant build" to create a new Ant configuration as follows:

• • In the "Main" tab, under "Buildfile" select "Browse workspace..." and choose {wonderland-source}/build.xml.
  • In the "Targets" tab check run-sgs (you might have to scroll way down to find it)
  • In the "JRE" tab select "Separate JRE" and pick your default JRE (must be 1.5 or above)
  • In the "Common" tab you might want to select "Display in favorites menu", which creates a handy shortcut in Eclipse's menu bar.

Repeat the above process, substituting "run" for "run-sgs" as the target. We now have two Ant configurations: choosing run-sgs runs the server, the other runs the client. Make sure everything works by running one after the other from Eclipse.

5) Now we are ready to add support for debugging. It turns out that Ant spawns separate JREs for each task and therefore, since they are not under Eclipse's control, breakpoints are ignored entirely. We must run our debugging tasks outside of Eclipse with special instructions for the compiler, asking it to listen for debugging instructions on a specific port:

• Open {wonderland-source}/build.xml, or one of the files in {wonderland-source}/build-tools/import if you cannot find your target in the main build file. For this example we are going to debug the server so let's open {wonderland-source}/build-tools/import/run-sgs.xml.
• Duplicate the entry for the task you want to debug - for this example, let's copy the entire contents of

  <target name="run-sgs"...></target>

  and paste it below the original entry.
• Rename this target to anything you like, for instance "run-sgs-remote-debug"
• Add the following compiler arguments to those already present in the

  <java...></java>

  section:

           <jvmarg value="-Xdebug"/>
           <jvmarg value="-Xnoagent"/>
           <jvmarg value="-Djava.compiler=NONE"/>
           <jvmarg value="-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9999"/>

Open a separate terminal window and call "ant run-sgs-remote-debug" (or whatever name you assigned to it) from {wonderland-source}. You should see the usual ant messages but when the final target is reached, the last line should be:

[java] Listening for transport dt_socket at address: 9999

• Go back to Eclipse and from the "File / New" menu select "New Java project." Name it "RemoteDebugging" or something similar and simply leave it empty as it is.
• From the "Run" menu choose "Open debug dialog..." Double-click on "Remote Java application" to create a new debugging configuration. Under the "Connect" tab, in the "project" line click "Browse..." and select the folder for the empty project you just created. In "Connection properties" on the same page enter "localhost" and "9999" (or any other port if you chose a different one).
• In the "Source" tab select "Add..." then "Workspace folder" and point it at {wonderland-source}/src/classes
• Save this configuration, add a breakpoint or two in the server code (for instance in the buildWorld() method in org.jdesktop.lg3d.wonderland.darkstar.server.cell.WorldRootCellGLO.java), and run the configuration. It should connect to the remote task you started earlier in a terminal, and stop at the breakpoint. Have fun examining the content of variables and stepping through the code!

Notes:

1) The above process must be repeated for debugging other parts of the code. For instance you would create a custom ant task extending the current "run" target in build.xml to debug the client from an external terminal, just like we did with the server. You would need to create a separate Eclipse debugging configuration similar to the one above too.

2) When terminating a process which you've started from inside eclipse under windows not all of the forked threads get properly terminated (on the mac, things seems to get cleaned up a little better). It's worth periodically going into the task manager, looking at processes and killing any zombie java processes. If you don't do this, wonderland will generate exceptions because it's not able to open the ports that it needs.

-- Main.ducheneaut - 14 Feb 2008