Geworkbench Eclipse Setup
From Informatics
see also: eclipse
There has been a progression on how to setup geworkbench in eclipse. Typically, one would just create a project (or check a project out from code repository, like Subvesion or cvs), and make sure all the jar dependencies are on the build path (in the .classpath file). We have had to deviate from this because of the size of the project. Specifically, geworkbench is a component based architecture, where one component can have same jars as another component but with a different version. That being said, setting up geworkbench the old way led to a multitude of classpath issues because all jars were added to the classpath. For some time, this was resolved by maintaining the order of the jars but as new components have been added with increasingly more jars (some with 60 jars), a new setup was needed. The new setup is described below.
Contents |
Setting Up geWorkbench
Java Version
After the release of geWorkbench 1.8.0, development of geWorkbench started to be under Java 6.
In case of supporting earlier versions or other need of using earlier versions of Java, see directions in eclipse for information on how to add a JDK.
First, create a new eclipse workspace dedicated entirely to geworkbench. To do this, you can do the following:
- Make a simlink of eclipse. In Windows, this is just a shortcut pointing to eclipse (you can copy the eclipse.exe icon, paste it, and rename to geworkbench).
- Right click on this new shortcut, select Properties, and add the following:
C:\java\apps\eclipse\eclipse.exe -clean -data c:\java\apps\eclipse_geworkbench_workspace -vmargs -Xms128M -Xmx900M -XX:PermSize=64M -XX:MaxPermSize=128M
(replace C:\java\apps\eclipse\eclipse.exe with your eclipse directory) If you use spaces in your paths, the path must be quoted. For example, if you put eclipse in C:\Program Files\eclipse, this would be quoted as "C:\Program Files\eclipse". The above string would then look like:
"C:\Program Files\eclipse\eclipse.exe" -clean -data c:\java\apps\eclipse_geworkbench_workspace -vmargs -Xms128M -Xmx900M -XX:PermSize=64M -XX:MaxPermSize=128M
If you see a gray message box when starting eclipse, this is probably because the -Xmx900M is larger than the amount of memory you have on your computer. Try reducing this number.
- Create a folder on your filesystem called eclipse_geworkbench_workspace (I have mine under "C:\java\apps").
- Change the path next to the -data flag to point to this new directory.
Now, when you click on the geworkbench icon, it should open eclipse and point to the geworkbench development workspace.
Setting up the Core
- Checkout a new project from Subversion. Use the location: use the repository location https://ncisvn.nci.nih.gov/svn/geworkbench/trunk/geworkbench/
Check this out using the New Project -> Project -> SVN ->Checkout Projects from SVN. By default, the name of the project will be geworkbench-core.
- Create a run configuration for geworkbench-core and set the following VM arguments:
- -Xmx600M -Dcomponents.dir=<path-to-eclipse-workspace>.
Setting up the Components
- Checkout a new project from Subversion. Use location https://ncisvn.nci.nih.gov/svn/geworkbench/trunk/geworkbench/components and select <your component>. Select Checkout as a project in the workspace.
Repeat these steps to get all components you need. Please note that all the subdirectories under geworkbench/components/ are not valid components. For example, some are projects that are not under active development. A good set of minimal components to use are:
- microarrays
- selectors
- analysis
- hierarchicalclustering
- somclustering
- aracne
- plots
The point below only has to be done once, for each new component/eclipse project (already done by Kiran for most components).:
- Right click on the project and select Properties. Under Java Build Path and under the Libraries tab select Add JARS. Add all jars in the lib directory for that component. Under the Source tab select Add Folder. Add the /src and /test folders (if /test does not exist, do not worry about it).
Running
Run with the following VM arguments:
-Xmx500M -Dcomponents.dir=<path-to-your-eclipse-workspace>
We use <path-to-your-eclipse-workspace> because that is where the components are based on the setting we describe above. If you want geworkbench to search a different directory for the components, you should put that directory for the -D argument. For example, -D./components will make it search the components subdirectory, which is default when geworkbench runs outside eclipse.
Main class:
org.geworkbench.engine.config.UILauncher
Run Configuration with User Interaction
When you create a run configuration, you can enter program arguments directly in the Arguments tab. Alternatively, you can prompt the user of the run configuration to enter a value. To prompt the user for a url, for instance, you would add the following to the Arguments tab.
-url ${string_prompt:the service url}
Running Ant with the Eclipse Configuration
- If you still want to be able to run geworkbench via ant with this eclipse configuration, create an environmental variable called ECLIPSE_HOME that points to your eclipse workspace, restart the command prompt (if it was open), and run:
- ant run-eclipse-config
working with DLLs
In the following example gpmodule-PCA v3.0 is using Java3D which comes with specific dynamic link libraries (DLLs) also called Native Libraries.
In order to make those accessible to geWorkbench in Eclipse one has to add the path where the libraries can be found to the Java Build Path under JRE System Library – Native Library Location. To do so go to the package explorer, right click geworkbench-core, properties, java build path, libraries. Find the JRE entry, expand the entry and add "geworkbench-core/lib" to native library location.
In fact this should enable us to put all specific DLLs into this directory (geworkbench-core/lib) and be much more independent from other installations, but I don't know enough about this issue. It just works for me... ;-)
Sharing a New Project
Checking in a Component
See details for sharing a project under eclipse and use the following path and module information:
1) use the repository location with https://ncisvn.nci.nih.gov/svn/geworkbench/trunk/geworkbench/components
2) select "Use project name as folder name"
Branching and Merging
Branching
All branching in eclipse should be done on geworkbench-core, then the associated components should be switched to the new branch. The exception is if you are only going to make changes to one specific component, such as the analysis component. In this case, you can branch on the individual component itself. See eclipse for general instructions on how to branch.
Note: If you are branching on geWorkbench-core, make sure you set the branching timeout to greater than just 60s before proceeding with the branching instructions.
Merging
First, read the directions on merging in eclipse under the eclipse help. This provides detailed instructions on how to set up your environment before you perform the merge. THIS IS IMPORTANT.
- Merge geworkbench-core if changes were made to this (don't merge the components directory).
- Merge the component.
