Building with Maven

Maven uses the notion of a build life-cycle to which plugins can attach. Plugins are similar to Ant tasks. When a Maven build is invoked, we specify a point in the life-cycle up to which the build should proceed. The compile phase comes before test, and test comes before package, and package comes before install. Once we have Maven setup, we can invoke the Struts build, and specify which phase the build should use.

TODOs

1.  Deploydb:
   - fix root/cloud permission issue
   - create cloud user is it does not exist
   - remove developer/pom.xml to a profile in root pom.xml
   - create schema/tables for cloud_usage and cloudbridge databases
2. Compile:
   - fix tomcat webapp compilation issue
   - fix compilation of some projects still under WIP
3. Deploy and Debug:
   - configure tomcat plugin to do tomcat:deploy and tomcat:run, debug
4. Packaging:
   - deb packaging
   - rpm packaging
5. Site/doc generation with maven

Installing Maven

Get Maven binary: http://maven.apache.org/download.html

For Mac and Linux:

Extract the latest stable binary release to /usr/local/maven

Add following to your .zshrc/.bashrc/.aliasrc:

export M2_HOME=/usr/local/maven
export PATH=${M2_HOME}/bin:${PATH}

*For Windows: *

Right click on my computer and click on Properties
Click on Advanced system settings
Click on Environment Variables
Click on New... under System variables
Add M2_HOME to Variable name and /usr/local/maven to Variable value
Find Path and click Edit...
Add ;%M2_HOME%/bin at the end
Click OK, OK, and close to get out of all the dialogues
Locate a copy of genosimage.exe.  It comes with cygwin and can be copied from %CYGWIN_HOME%\bin
copy %CYGWIN_HOME%\bin\genosimage.exe %SOURCE_HOME%\mkisofs

Understanding POMs

POMs are top level build configuration files.

To debug POMs, read through the effective POM:

$ mvn help:effective-pom

Dependencies for ant

Running mvn in source root will download and setup dependency jars the deps directory for use with the old ant system.

$ mvn -P deps install 

Some modules require dependencies that are not freely available or have an incompatible license. These dependencies you need to donwload yourself. See to following instructions to add them to your maven repository.

1. Download the following jars and put them in the deps directory:

• cloud-iControl.jar
• cloud-netscaler.jar
• cloud-netscaler-sdx.jar
• cloud-manageontap.jar
• vmware-vim.jar
• vmware-vim25.jar
• vmware-apputils.jar

2. Go into the deps directory and run install-non-oss.sh

$ cd deps
$ ./install-non-oss.sh

Building CloudStack

Running the maven command in the top directory of the CloudStack sources will compile all sources for CloudStack. The resulting jar files will be in the directory target in the subdirectory for a particular module. The default build will have all components that depends on non opensource (non-oss) libraries disabled. If you want to enable this, just add -D nonoss to the mvn command line or see the table below for more fine-grained options. The install goal will compile all sources, make war and jars files and add he to your local repository.

$ mvn clean
$ mvn install

Example, if you want to build CloudStack with all ASF components and the vmware plugin, use the following command

mvn -P vmware install

Deploying Database

Note: The following is a WIP feature, use the above Ant command for now.

$ mvn -P developer -pl developer -Ddeploydb

Running a server for test/debug purposes.

This will run a jetty server on localhost port 8080 with the management server.

$ mvn  -pl :cloud-client-ui -am jetty:run

Note: The following is a WIP tomcat-plugin feature, use the above jetty command for now.

$ mvn org.apache.tomcat.maven:tomcat7-maven-plugin:2.0-beta-1:run -pl :cloud-client-ui -am -Pclient

Open the following URL on your browser to access the Management Server UI:
    http://localhost:8080/client/
Or,
    http://management-server-ip-address:8080/client

The default credentials are; user: admin, password: password and the domain
field should be left blank which is defaulted to the ROOT domain.

Temporary Build Process on ASF Master

This build process is based on ant, waf and maven. In future, we'll try to have maven do everything for us.

$ cd incubator-cloudstack
$ mvn -P deps # gets
$ ant clean-all build-all
$ ant deploy-server # ant deploy-server before you deploydb
$ ant deploydb # checkout how to deploy db with mvn above; usual ant stuff :)

To buid with nonoss plugins we need to apply a patch and copy nonoss libs (cloud-iControl.jar, cloud-netscaler.jar, cloud-netscaler-sdx.jar, cloud-manageontap.jar, vmware-vim.jar,vmware-vim25.jar, vmware-apputils.jar) to /deps:

$ wget http://bhaisaab.org/patches/cloudstack/0001-BUILD-Make-CloudStack-buildable-with-nonoss-libs.patch
$ git pull <branch; master>
$ git am <patch>
$ mvn -P deps
$ ./waf rpm # or, do ant build-all etc.

For nonoss builds only: After installing these packages, user is required copy nonoss libs in /usr/share/java (or some place) and update classpath to each jar in /etc/cloud/management/classpath.conf

Building RPM packages

Use waf to build packages for linux systems that use rpms, like RedHat, CentOS and fedora.

$ waf --package-version=4.0.0 --prerelease=rc1 --build-number=1 --oss rpm

$ mvn install -P deps && ./waf rpm

Building DEB packages

On Master:

$ mvn install -P deps && dpkg-buildpackage

Package using deb profile (feature under development uses jdeb plugin, in https://github.com/bhaisaab/incubator-cloudstack/tree/debs-maven debs-maven branch):

$ mvn package -P deb

Development with a IDE

Good Ol' Terminal

Zsh/Bash/Emacs/Vim/Grep/Sed/Awk/Javac...

$ sh deps/install-non-oss.sh

$ mvn -Dnonoss install

$ ant debug # Good ol' way of doing things

IntelliJ IDEA

FIXME: Add on how to use IntelliJ IDEA with CS, building, debugging, editing, git checkouts

Eclipse

The move to maven also means that a better integration with Eclipse is possible. To setup maven make sure that the latest version of the m2e plugin is correcly installed.

You can checkout the project yourself and import it as a maven project using the Eclipse UI, or directly checkout the maven project using the checkout from SCM option in the maven section of the import dialog.

For easy building and launching you can setup several run configurations. I'm using the following configurations:

• CloudStack rebuild (full rebuild of cloudstack code)
  Base directory: ${project_loc:cloudstack}
  Goals: clean install
  Profiles: <empty>
• CloudStack launch (launch the jetty based management server)
  Base directory: ${project_loc:cloudstack}
  Goals: -pl client jetty:run
  Profiles: <empty>
• CloudStack rebuild (full rebuild of cloudstack code)
  Base directory: ${project_loc:cloudstack}
  Goals: -pl developer
  Profiles: developer
  Parameters: deploydb = true

Other Uses

RAT: ASF License Checking

$ mvn --projects='org.apache.cloudstack:cloudstack' org.apache.rat:apache-rat-plugin:0.8:check

The output file is in ${project.build.directory}/rat.txt, by default in target/rat.txt

Site Generation and Reporting

$ mvn site

Versioning / Releases

Update the version number of the project

mvn release:update-versions -DautoVersionSubmodules=true -Dnonoss -Pdeps,developer -DdevelopmentVersion=<version>-SNAPSHOT

Releases can also be done using the release plugin. This plugin will automagically take care of setting the currect version (removing the -SNAPSHOT), making a tag in SCM and deploying the jars to the maven repository. This should only be executed by the release engineer. Maven assumes that once a version is released it will never change anymore and released binaries will never be updated, so any subsequent releases will have to bump the version number.

Troubleshooting

• Offline Mode:

Set commandline parameter -o to force maven to only use the local repository. This might trigger build failures if artifacts are not available locally, but might speed up the build process in some cases.

$ mvn -o 

• Out of memory error, out of heap space:

// Bash
export MAVEN_OPTS=-Xmx512m
// Windows
set MAVEN_OPTS=-Xmx512m