...

First of all, you need the Whirr source code. Checkout subversion git "trunk" using:

svngit checkoutclone httpgit://svngit.apache.org/repos/asf/incubator/whirr/trunk/ whirr-trunk.git

Setting up Eclipse

Generate the Eclipse project and classpath files:

mvn eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs

(NOTE: If this fails because whirr jars aren't found in a remote repo, run mvn install first as described in the next section then retry.)

In Eclipse, set Set the M2_REPO classpath variable: 1.

1. File, Preferences, Java, Build Path, Classpath Variables

...

1. New

• Name: M2_REPO
• Path: /path/to/.m2/repository

Import Then import all projects: 1.

1. File,

...

1. Import, General, Maven, Existing

...

1. Maven Projects
2. Choose the whirr-trunk directory

...

1. Choose all modules

It's also convenient to add the top-level directory as an Eclipse project too.

...

Build and install the JARs from the top-level with the following

mvn install -DskipTests

To check the code adheres to the style guidelines, which are Sun's conventions except 2 spaces for tabs, http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html^{Image Removed}, you can use

mvn checkstyle:checkstyle

Normally you don't need to deploy to remote repositories (this is covered in How To Release), but you can test local deployment with

mvn deploy -Ppackage -Pdeploy -Pjavadoc -DaltDeploymentRepository=id::default::file:target/deploy

Running Tests

Unit Tests

You can run the unit tests, which run locally without using any cloud providers, by typing:

mvn test

Integration Tests

To run integration tests you need to have an account with a cloud provider, and you need to set the necessary credentials. In theory, Whirr runs against any provider supported by jclouds, but this hasn't been tested yet.

When running in the cloud, you can avoid problems if RAM resources are slim by setting env var:

export MAVEN_OPTS=-Xmx200m

and by running the mvn commands below like

nice -n 19 mvn ...rest of args

; when tests are run with no specified heap limit, it can result in swapping and then ssh lockout.

To only run the tests for a given service, change into the services/<service> directory and type the following. Alternatively, run this from the top level to run the tests for all services.

mvn verify -Pintegration \
  -DargLine='"-Dwhirr.test.provider=<cloud-provider> -Dwhirr.test.useridentity=<cloud-provider-user> -Dwhirr.test.keycredential=<cloud-provider-secret-key>'"

For Amazon EC2, whirr.test.provider should be set to aws-ec2 (the default). The user identity is the access key ID, and the key credential is the secret access key.

The tests also rely on having an SSH keypair. By default they use .ssh/id_rsa and .ssh/id_rsa.pub in the user's home directory, but you can override this by setting by providing an extra config file as follows. Here we specify a file called .whirr-test.properties in our home directory.

mvn verify -Pintegration \
  -DargLine="-Dwhirr.test.provider=<cloud-provider> -Dwhirr.test.identity=<cloud-provider-user> -Dwhirr.test.credential=<cloud-provider-secret-key> -Dconfig=.whirr-test.properties"

The property whirr.test.provider must be set on the command line as specified; it does not work to set it in the config= file.

Integration tests test the correctness of services on different providers. To test performance have a look at Running Benchmarks.ssh.keyfile to the private key's filename.

Contributing your work

Patches should be ''attached'' to an issue report in JIRA via the '''Attach File''' link on the issue's Jira. Please note that the attachment should be granted license to ASF for inclusion in ASF works (as per the Apache License).

You can also use the Apache Review Board instance at https://reviews.apache.org/ for review, although this is optional, and you still need to attach the patch to JIRA.

When you believe that your patch is ready to be committed, select the '''Submit Patch''' link on the issue's Jira.

...

Once you have submitted your patch, it will go into the Whirr Review Queue, then a committer should evaluate it within a few days and either: commit it; or reject it with an explanation.

...

Committers: for non-trivial changes, it is best to get another committer to review your patches before commit. Use Submit Patch link like other contributors, and then wait for a "+1" from another committer before committing. Please also try to frequently review things in the patch queue.

Post commit

After a patch has been committed, Hudson will run the unit tests.

Committing Guidelines for committers

...