Overview

The steps described below are designed to allow you to quickly build RHQ in as few steps as possible. After you become more familiar with the code base and more proficient with the build system, you should check out our Advanced Build Notes for additional things you will find helpful in working with the RHQ Maven build system.

If you do not want to build RHQ from source, you can instead download a binary distribution.

If you want to get familiar with how each of the individual modules in the source tree contribute to the overall built product, please read the Module Overview.

Install JDK

1. Download the latest release of JDK 7 available for your OS from either Oracle here or OpenJDK and install it.

2. Set the following environment variables in your .profile (UNIX) or System environment (Windows) - you must ensure you set these if you have multiple Java installations on your box, to ensure Maven picks up the correct JDK that you want to use:

   • JAVA_HOME=JDK7_install_dir

   • PATH=$JAVA_HOME/bin:existing_PATH

Install Maven

1. Download the latest release of Maven 3.x from http://maven.apache.org/download.html.

2. Unzip it somewhere on your system (e.g. C:\opt, /opt/maven).

3. Set the following environment variables in your .profile (UNIX) or System environment (Windows):

   • MAVEN_HOME=maven_install_dir

   • MAVEN_OPTS="-Xms256M -Xmx768M -XX:PermSize=128M -XX:MaxPermSize=256M -XX:ReservedCodeCacheSize=96M"

   • PATH=$MAVEN_HOME/bin:existing_PATH

Install Git

RHQ uses git for source code control. In order to download ("checkout") the sources, you need to have a git client installed.

Access to the git repository can be done via the git command line or via a plugin to your IDE.
To run git commands independently of your IDE, you can install git from http://git-scm.com/download.

• Eclipse - Eclipse now hosts the git plug-in which provides some of the git features. For info on the Eclipse git plug-in, see http://www.eclipse.org/egit/.

• IntelliJ IDEA - IntelliJ 9 and later has built-in support for git.

Install and Create Database for PostgreSQL

1. See the PostgreSQL Quick Start Installation Guide to install and configure PostgreSQL

2. Make sure to create the rhqadmin user and rhq database. Note: to ensure the initial mvn build below succeeds, you also need to have created a database called "rhqdev".

Checkout RHQ Sources

1. Open a command prompt and cd to the directory where you want the RHQ sources to live, e.g.:

   cd ~/projects

2. Clone the RHQ source from the git repo:

   git clone git://git.fedorahosted.org/git/rhq/rhq.git

   or if your firewall prevents using the git protocol you can also clone via http (much slower though)

   git clone http://git.fedorahosted.org/git/rhq/rhq.git

   or for developer access:

   Developer access

   git clone ssh://git.fedorahosted.org/git/rhq/rhq.git

   SSH properties

   Note: if your fedora user name is different from the local one or you have a different public key for
   fedora than some default one, you need to specify it to git/ssh.
   To do so you can add this to ~/.ssh/config:

   $ cat  ~/.ssh/config
   
   Host git.fedorahosted.org
   IdentityFile id_fedorahosted_rsa
   User joedev

   So in this example the fedora user is joedev and the ssh key is in ~/.ssh/id_fedorahosted_rsa

Build RHQ

1. Make sure you have set up the settings.xml file as described in Advanced Build Notes including uncommenting the postgres profile.

2. Make sure you have the Databases set up 

   createuser rhqadmin
   createdb -O rhqadmin rhq
   createdb -O rhqadmin rhqdev

3. Open a command prompt and cd to the directory where the RHQ sources live, e.g.:

   cd ~/projects/rhq

4. Build RHQ:

   mvn -Penterprise,dev -Ddbsetup -DskipTests install

   NOTES

   • The first time you build RHQ, it will take up to an hour, because it will need to download many 3rd party dependency jars for both RHQ and Maven itself. Subsequent builds will be significantly faster, especially if you only build specific modules.

   • "-Ddbsetup" is only required the first time you build; thereafter, the schema will be created in your database, and you won't need to do it again unless a) the schema changes and needs to be rebuilt or b) you want to clean out your database and rebuild the schema.

   • You do not need to rebuild your container after performing a subsequent -Ddbsetup, but you will want to restart your agent --fullcleanconfig.

   • The RHQ BuildNumber is set to the git sha1.

   • If you have been building RHQ for a while and you notice that the versions of any dependencies in the dependencyManagement section of the root POM have changed due to a recent commit, you MUST build from root. If you don't, the {m2_repo}/org/rhq/rhq-parent/{currentVersion}/rhq-parent-{currentVersion}.pom file will be stale, and will be used when resolving dependencies locally, and thus you won't resolve to the latest dependencies. If you don't want to take the "hit" of building from root, you can build ONLY the root module by saying "mvn -N install" from the root, which will update the aforementioned POM in your local repository without building all modules.

   • If you run into test failures, run with the option -DskipTests so that those will be still built, but not executed. -Dmaven.test.skip will also skip building them and subsequent compilation will fail.

Running RHQ

Switch to the RHQ bin directory. If simulating production:

cd <rhq-root>/modules/enterprise/server/appserver/target/rhq-server-<version>/bin

If using the dev-container:

cd <rhq-root>/dev-container/rhq-server/bin

> ./rhqctl install

Run the RHQ CLI

You can also run your build of the RHQ CLI:

cd <rhq-root>/modules/enterprise/remoting/cli/target/rhq-remoting-cli-<version>/bin
./rhq-cli.(sh|bat) -u rhqadmin -p rhqadmin

See Running the RHQ CLI for more information about the CLI environment.

IDE

If you want to contribute to RHQ, you can load the code base in your favorite Java IDE. We have some tips for the big two here:

• Eclipse

• IntelliJ IDEA