Build Instructions - General
Check out the source
Firstly, check the source for Qpid java out of our subversion repository:
https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid/java
You will also need to checkout the gentools directory at the same level:
https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid/gentools
and python:
https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid/python
and finally the protocol specification:
https://svn.apache.org/repos/asf/incubator/qpid/trunk/qpid/specs
Prerequisites
For the broker code you need JDK 1.5 or later. You should set JAVA_HOME and include the bin directory in your PATH.
Check it's ok by executing java -v !
If you are wanting to run the python tests against the broker you will of course need a version of python.
Build Instructions - Trunk (M2+)
Maven Build System
Useful Maven links
Install Maven 2
Firstly, you need to install Maven 2 from here).
You can find out how to set Maven up by following their quick guide.
Some of the relevant Maven targets (in Maven speak 'lifecycle phases') are as follows:
Phase |
Description |
---|---|
compile |
compile the source code of the project |
test |
test the compiled source code using a suitable unit testing framework |
install |
compiles & installs the package into the local repository & generates JAR files |
clean |
cleans up artifacts created by prior builds |
You can run the install phase but skip the tests by running:
mvn -Pfastinstall
to specify the fastinstall profile.
You can just skip the python broker tests by adding this -D option. This is done when using the fastinstall profile above.
-Dskip.python.tests
NOTE When running under cygwin on windows the version of python that runs can give the following error "c:\windows\system32\ntvdm.exe Error while setting up environment for the application. Chose 'close' to terminate the application."
This is due to the windows python being picked up rather than the cygwin version. When run from a cmd.exe window everything should work. If you wish to run it from a cygwin window the following option should be added to your mvn command line.
-Dcommand="bash -c 'python run-tests -v -I java_failing.txt'"
You can now also run the install phase with retrotranslator (for building the Java client in JDK 1.4) running:
mvn -Pretrotranslator
Build Qpid Java
To compile & install Qpid, cd into the java directory of your checkout and then:
mvn clean mvn install
If you wish to build an archive of Qpid for installing somewhere then:
cd distribution mvn
NB: executing Maven in the distribution directory does NOT force a clean build or a re-JAR, but uses the jars from your repository. You must be sure to execute a clean install in the java directory first (up one level from the distribution directory) to get a clean distribution. Best to check that the jars in your repository are current before building a dist!
Build/Debug Cycle
If you're changing code as part of a debugging effort and want to quickly rebuild and then run the broker for manual testing, you can use the following commands, starting in the top-level java
directory:
mvn -Pfastinstall cd distribution mvn assembly:directory
The first command above builds everything but skips the tests. The last command above builds the normal distribution but also creates a directory holding the contents of the Java bin assembly. You can run the broker directly from that directory by setting QPID_HOME
to point to it. For example, for the Qpid incubating 1.0 M2 snapshot version, the assembly directory resulting from running the final command above is:
target/qpid-1.0-incubating-M2-SNAPSHOT-java-bin
If you set the QPID_HOME
environment variable to the directory contained within the directory named above, i.e.:
target/qpid-1.0-incubating-M2-SNAPSHOT-java-bin/qpid-1.0-incubating-M2-SNAPSHOT
and add $QPID_HOME/bin
(UNIX) or %QPID_HOME%\bin
(Windows) to your PATH
, you can then run the broker by executing the qpid-server
script.
You can also control where the assembly directory is built via the qpid.targetDir
property, like this:
mvn -Dqpid.targetDir=/tmp/xyz assembly:directory
This will create the assembly directory and the various tar and zip files in directory /tmp/xyz
.
In summary, with QPID_HOME
set as described above, the edit/build/debug cycle becomes a matter of first rebuilding the appropriate artifacts, either from the top level or within the specific subdirectory for a single modified artifact, changing to the distribution
directory, and creating the assembly directory as described above. You can then run the broker via qpid-server
and perform your debugging, testing, etc.
Building Project Files
You can build project files for IntelliJ IDEA and Eclipse IDEs by executing the appropriate command in the java directory:
Command |
Result |
---|---|
mvn idea:idea |
Builds .ipr and .iml files with appropriate project settings for classpath etc |
mvn eclipse:eclipse |
Builds Eclipse project files with settings |
To get started with Eclipse, use the setup.eclipse
profile:
mvn -Psetup.eclipse
The setup.eclipse
profile will by default create an Eclipse workspace in the ../workspace
directory. You then go into Eclipse, switch to the new workspace, and then import the Qpid projects by selecting File -> Import -> Existing projects into workspace.
If you want to set up a workspace other than ../workspace
, you can specify it on the command line via the eclipse.workspace.dir
property:
mvn -Declipse.workspace.dir=/path/to/workspace -Psetup.eclipse
Build Instructions - M1 branch
Ant Build Scripts
Currently the Qpid java project builds using ant.
The ant build system is set up in a modular way, with a top level build script and template for module builds and then a module level build script which inherits from the template.
So, at the top level there are:
File |
Description |
---|---|
build.xml |
Top level build file for the project which defines all the build targets |
common.xml |
Common properties used throughout the build system |
module.xml |
Template used by all modules which sets up properties for module builds |
Then, in each module subdirectory there is:
File |
Description |
---|---|
build-module.xml |
Defines all the module values for template properties |
Build targets
The main build targets you are probably interested in are:
Target |
Description |
---|---|
build |
Builds all source code for Qpid java |
archive |
Generates all distribution archives for Qpid java |
So, if you just want to compile everything you should run the build target in the top level build.xml file.
If you want to build an installable version of Qpid java, run the archive task from the top level build.xml file.
If you want to compile an individual module, simply run the build target from the appropriate build-module.xml e.g. to compile the broker source, simply run the build target in the java/broker/build-module.xml file.
What next ?
If you want to run your built Qpid package, see our Getting Started Guide for details of how to do that.
If you want to run our tests, you can use the ant test or testreport (produces a useful report) targets.