Advanced Build Notes
Below are some notes and information regarding the RHQ build system. They provide some tips that should enable you to more efficiently build and develop the RHQ platform. If you are looking for basic step-by-step instructions on how to build RHQ, see the Building RHQ page.
settings.xml
You can customize how Maven performs its builds by creating for yourself a settings.xml file and placing that file in the $HOME/.m2 directory. There is an example settings.xml checked into the SVN repository at etc/m2/settings.xml. If you look at that file, you'll see you can do things like:
- Enable the dev profile by default (see below for more information on this RHQ-defined profile).
- Disable the tests by default (Maven's default is to always enable tests unless you specify -Dmaven.test.skip; you can define this in your settings.xml if you do not want to run the tests by default)
- Define locations of several databases, if you want to compile and test with different databases
- Define locations of additional Maven repositories
- Define the location of your external RHQ Server location (rhq.containerDir - see below for more)
- et. al...
The enterprise Profile
The RHQ Maven build infrastructure defines a Maven profile called enterprise. This effectively builds the fully contained and ready-to-run RHQ Server container (which includes the JBoss Application Server and all its custom configuration and deployment files that go with it).
To build the RHQ Server container, you enable this enterprise profile by passing the command line option -Penterprise to the mvn executable when building from the root module: e.g. mvn -Penterprise install.
 | In order to understand things like profiles and modules, you should be familiar with Maven. Read the Maven documentation for more information. |
The enterprise profile is very simple - all it does is enable the building of the modules/enterprise/server/container Maven module when building RHQ from the root module. You get the same effect as -Penterprise if you were to change your current directory to modules/enterprise/server/container/ and execute mvn install.
After you have built the RHQ Server container, you will find it under the directory modules/enterprise/server/container/target/rhq-server-\<version>. This is a fully contained and ready-to-run RHQ Server. See Building RHQ#Run RHQ for the detailed steps on running the RHQ Server from this location.
Note that this modules/enterprise/server/container module will, by default, build an RHQ Server that needs to have its installer run. This is because the user needs to tell the RHQ Server things like database connection information, the IP address that the RHQ Server should bind to, etc. The installer also needs to deploy things that aren't ready to deploy until the user answers some questions. For example, you will see several directories and files under jbossas/server/default/deploy/ that are appended with ".rej". This tells the JBossAS server to reject those deployment artifacts and will not process them. After the user answers some questions, the installer will rename those by removing the ".rej" causing the JBossAS server to deploy them. None of this is pre-deployed when you build with -Penterprise and is why you need to run the installer to complete the configuration and deployment of the RHQ Server. See Installing#Running The Installer for information on the installation process.
If you are developing RHQ, you usually build with the -Pdev profile so you can build a "predeployed" RHQ Server container that doesn't require the installer to be run. See below for information on this dev profile.
Note that tomcat will not reloaded web applications when the RHQ server container was build with -Penterprise.
You either need to build it with -Pdev or modify jboss-web.deployer/context.xml to use 'reloadable="true"' at the top of the file.
The dev Profile
The RHQ Maven build infrastructure defines a Maven profile called dev. You typically enable this profile when you are developing RHQ and building it often. The dev profile helps speed up the building process and will copy the RHQ modules' build artifacts to an external RHQ Server location, allowing you to have an RHQ Server that you constantly update so you can avoid having to build a full RHQ Server every time you want to run it.
When you first built RHQ, you probably enabled both the enterprise and dev profiles by passing to mvn the command line option -Penterprise,dev (which is the same as if you specified -Penterprise -Pdev). Because you enabled the enterprise profile, you told Maven to build the modules/enterprise/server/container module (see the section above for more info on this). But because you also specified the dev profile, you told Maven to take the RHQ Server container that the enterprise profile built and copy it to an external container directory (by default, it will be a new directory under your trunk directory called dev-container). This external container directory (<trunk>/dev-container by default) is a fully contained and ready-to-run RHQ Server and you configure and run it like any other.
| Your $HOME/.m2/settings.xml Maven configuration file can be used to tune how certain things are built. One of the Maven properties you can set is rhq.containerDir - this is a full path to a directory where you want your external container location to be. If this is not set, "<trunk>/dev-container" is the default. |
Now that you have built your container, you do not have to build it again (unless, of course, something in the container module changed, in which case you will need to rebuild it again). Now you can simply build with the -Pdev profile enabled, but you do not need to enable the -Penterprise profile. All of the RHQ Maven modules have rules defined that will run when the dev profile is enabled - usually it means the Maven module will simply copy its build artifacts to your external container location (i.e. your rhq.containerDir).
Let's go over an example for how this is helpful and speeds development. Suppose you have already built your RHQ Server and have it stored in your external location at /my-rhq-server (that is, your settings.xml defines rhq.containerDir as "/my-rhq-server"). Suppose that I modified a .xhtml page in the UI and I want to see my change. I can go to the modules/enterprise/gui/portal-war module, and build it with the dev profile: mvn -Pdev install (to make it even faster, I can turn off the unit tests by passing in the -Dmaven.test.skip property). The portal-war module will build the portal war and, because dev profile is enabled, will copy all of its build artifacts to your external location under /my-rhq-server. You do not have to rebuild the entire server again, you just need to rebuild the module that changed. The dev profile will copy the changed artifacts to their appropriate locations within your external container.
| If the RHQ Server was already running, you do not have to shut it down and restart it when changing UI code. The underlying JBossAS server is configured to allow for UI components to be hot-deployed during runtime. The same is true for plugins - if you've changed a plugin, just rebuild it using -Pdev and the plugin jar will be copied in the appropriate location in the RHQ Server. The RHQ Server will pick up the change, deploy the plugin properly and your agents will then be free to update their plugins to pick up the new one (see the agent's "plugins update" prompt command for one way to do this). |
Debugging Unit Tests
If you do not set -Dmaven.test.skip=true when you run a mvn build, the unit tests will execute. If you wish to debug a unit test with a JPDA-enabled IDE, you can pass in the system property -Dtest.debug which will launch the TestNG environment with JPDA enabled, listening on the socket port #8797. Connect your JPDA-enabled IDE to that port and you'll be able to step through the code.
Building With Oracle
Due to licensing restrictions, the RHQ project is not permitted to host the Oracle JDBC drivers on a public Maven repository. Because of this, the default RHQ build will not attempt to pull down the Oracle JDBC drivers. If you have access to a Maven repository that contains the Oracle JDBC drivers, and you set up Maven to access that repository (in settings.xml, for example) you can pull them down to your local repository by using the mvn command line option "-Pprod". This will enable the RHQ-defined prod Maven profile, which will tell the build to add the Oracle JDBC driver to the set of dependencies that should be pulled down. The Oracle JDBC driver will also be pulled down if you build the Oracle agent plugin (which has the Oracle JDBC driver as an explicit dependency). The Oracle agent plugin module is not a part of the default RHQ Maven build so it will not be built unless you explicitly do it (by running the "mvn install" command from within the modules/plugins/oracle directory).
Downloading Source
If you want to see the source code for RHQ's third-party dependency libraries, you can ask Maven to download any and all available source jars by issuing the command mvn dependency:sources. If a public Maven repository has the sources available, they will be pulled down to your local repository.
Debugging a Running Agent
To start the agent such that you can connect a JPDA debugger (such as Eclipse) to it, simply set the RHQ_AGENT_ADDITIONAL_JAVA_OPTS environment variable so it contains your VM's appropriate JPDA settings and start the agent normally. You can then use your debugging tool to connect to your VM. Example options are:
