Using Eclipse With CloudStack

As part of switching to Apache Maven for building CloudStack, the .classpath and .project files used by Eclipse were removed. This page describes how to get CloudStack loaded into an Eclipse workspace. For more details on the actual build process with maven see How to build CloudStack

Use a Recent Eclipse Build

These steps have been tested with Eclipse Indigo and Eclipse Juno- it's suggested you use that or a newer build.

Start with a clean workspace

To minimize confusion, start with a clean workspace with no other projects.

Clone CloudStack via git

Download the CloudStack source code via git with:

git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git

Install M2E

This wiki page shows how to install the Maven integration for Eclipse plugin. (For those using Yoxos, just search for M2E and add it to your Eclipse build)

After installing the plugin, restart Eclipse.

Import CloudStack

Now you can import CloudStack using the M2E plugin:

Go to File->Import...
Under Maven select "Existing Maven Projects" and click Next
Browse to and select the root directory of the CloudStack source tree. Once selected, Eclipse will scan the source for pom.xml files. Make sure all are selected, then click the Finish button.

Eclipse will import the projects and build the code. At this point you should be able to develop and debug code as usual within Eclipse.

Making Eclipse Work Better with CloudStack

Give Eclipse More Memory

CloudStack is a big project and it requires more memory for Eclipse. Here's how to give it more memory.

cd [eclipse home]
vi eclipse.ini
Change or add the following properties
- -Xms1024m
- -Xmx2048m
- -XX:PermSize=512m
- -XX:MaxPermSize=1024M

Eliminate duplicate resources

CloudStack has a lot of projects that are really just for grouping the different type of projects. The problem is in Eclipse, the files that belong in sub-projects also show up in the projects. This causes a lot of problems with the Open Resource dialogue, which is often used to quickly get to a file if you know the filename already. These problems include the multiple copies of the same .class files showing up and multiple copies of the same .java file showing up. If you select the wrong .java file, then a lot of the references doesn't work. Upon further inspection, the reason is because the same .java and .class file is included by both the project and the parent project. To get rid of this problem, do the following. Unfortunately, you have to do this for every parent project.

Right click on the project and select Properties.
Go to Resource->Resource Filters.
Click on Add...
Select Exclude all
Select Folders
Click Regular Expression
In the entry box, type [a-zA-Z0-9].*
Click OK
Click OK

What this does is to tell Eclipse that the sub-directories under parent projects should not be included in the resource list, thus avoiding the the duplicate resources in the Open Resource dialogue box. If the parent project does have a directory that you want, then you can add that to a include filter. Note that you can not use * as the folders because that would exclude the .settings folder which eclipse uses to keep its metadata and will cause the m2e plugin to have problems.

Here's a list of parent projects you should do this with:

cloudstack
cloud-services
cloudstack-framework
cloud-engine
cloudstack-plugins

Avoiding conflicts between builds outside of Eclipse and Eclipse's auto-building

Eclipse by default uses the the Maven pom.xml to tell it where to put its generated files. Unfortunately, that has one big disadvantage. Everytime a "mvn clean" is done outside of Eclipse, Eclipse will start rebuilding. To avoid this, CloudStack has an Eclipse profile that puts all of the Eclipse generated files in a directory called target-eclipse. In order to activate this, you must do the following to every project. There is a shortcut for the existing projects so please read the shortcut first before deciding to do the following. You still need to perform these steps manually if a new project is added after you ran the shortcut.

Right click on the project and select Properties
Select Maven
In the entry box under "Active Maven Profile", type in eclipse
Click OK

CloudStack has a lot of projects so doing the above by hand for every project takes time so here's a shortcut provided for existing projects.

Exit Eclipse (assuming you've already installed the m2e plugin)
cd [cloudstack home]
bash -x tools/eclipse/set-eclipse-profile.sh
Restart Eclipse

Bonus Track: Running CloudStack Through Eclipse

The Maven integration makes it reasonably easy to run and debug CloudStack through Eclipse. Basically, you can add the 'mvn' command-line calls to your Eclipse Workspace by defining corresponding Run Configurations.

The Maven commands we want to add as Run Configurations are discussed in detail on the How to build CloudStack page. The steps we want to add can be summarised as

Clean (remove previous versions of source).
Install (build new version of source)
Database Setup (deploy a database with default settings, e.g. default password)
Jetty-based server launch (Jetty is an alternative to Tomcat suited to development)

Now, we could have combined steps 1 & 2 above, but splitting them allows incremental compilation. In contrast, combining them will make for a very slow build. Also, you only need to setup the database once after doing a Clean.

WRT to debugging: Use the Jetty-based server lauch. First, tweak this Debug Configuration for source-level debugging: Use Run -> Debug Configurations, and check the Resolve Workspace Artifacts flag.

Creating a Run Configuration

For each Run Configuration to be added:

From menu bar, select Run -> Run Configurations...
Double click on Maven Build. This will create a Maven run configuration with the name New_configuration
Update the Name to something corresponding to what happens in the step, and set Base Directory to $project_loc:cloudstack (This tells Eclipse that the base directory for execution is the folder with a _pom.xml_ that has an <artifactId> with the value cloudstack)
From each mvn command, place the -P argument in the Profiles: textbox, Add... any parameters expressed as key=value , and place the remainder of the command in the Goals: textbox.

Maven will download everything needed to run CloudStack with Jetty, build the code, and run the UI. You can connect to it via http://localhost:8080/client.

The following commands were correct at the time of writing. If they don't work, double check the How to build CloudStack page, and if you have any compassion update this section of the wiki.

Clean:

mvn clean

Base directory: $project_loc:cloudstack
Goals: clean install
Profiles: <empty>

Install (i.e. build):

mvn install

Base directory: $project_loc:cloudstack
Goals: clean install
Profiles: <empty>

Deploy Database (do once after a 'Clean'): mvn install:

mvn -P developer -pl developer -Ddeploydb=true

Base directory: $project_loc:cloudstack
Goals: -pl developer
Profiles: developer
Parameter Name: deploydb=true

Jetty-based launch (of management server)

mvn -pl client jetty:run

Base directory: $project_loc:/cloud-client-ui
Goals: jetty:run
Profiles: <empty>

(Optional) launch the jetty based awsapi server:

mvn -pl awsapi jetty:run

Base directory: $project_loc:cloudstack
Goals: -pl awsapi jetty:run
Profiles: <empty>

Remote Debugging

You can use Eclipse to attach to the Management Server and debug CloudStack. You setup a Remote Debug Session (Run > Debug Configuration), connect to Port 8787. Typically you would use the project you want to debug as the target and include other projects that you need to debug, e.g. cloud-agent, cloud-api, cloud-core and cloud-server.