Table of Contents |
---|
Source
Build Instructions - General
...
Firstly, check out the source for Qpid out of our subversion repository:from the git repository.
git clone https://
...
git-wip-us.apache.org/repos/asf/
...
Prerequisites
qpid-broker-j.git qpid-broker-j
Prerequisites
Java
The build requires a Java 8 or For the broker code you need JDK 1.5.0_15 or later. You should set the JAVA_HOME environment variable and include the its bin directory in your PATH.
Check it's ok OK by executing the following at your command prompt.
java -
...
version
Maven
The build requires a Maven version of 3.0.0 or later. You should set the M2_HOME environment variable and include its bin directory in your PATH.
Check it's OK by executing the following at your command prompt.
mvn --version
Qpid Maven Structure
For complete reference and documentation on Maven please visit the following online resources.
Maven: The Complete Reference by Sonatype
Project Object Model (POM)
Each Qpid java module has its own POM file (pom.xml) located in its root directory.
This file defines the modules version, dependencies and project inheritence as well as the configuration of the relative maven plugins specific to this module.
At present we have 2 high level "parent" modules that serve as the grandparent and parent of all the java modules in the project.
POM | Artifact Name | Location | Description |
---|---|---|---|
Qpid Parent | qpid-parent | NA | This is the high level POM that all Qpid modules ultimately inherit from. It itself is a child of the latest Apache parent POM and its main purpose is to initialise all of our default values, plugins and versions and set any global Qpid configuration. It is versioned separatley and its release cycle is independent of that of the Qpid Java Project. |
Java Build | qpid-java-build | pom.xml | This is the primary build POM that can be used to build the whole Qpid Java project. It defines all of the Java Qpid modules and sets all the default values, plugins, versions and configuration for the whole Java build. |
Child Modules | qpid-* | **/pom.xml or **/**/pom.xml | Each and every child module has its own specific POM file that specifies exactly what its dependencies are and any plugin configuration it needs. |
Maven Commands
Here is a quick reference guide outlining some of the maven commands you can run and what the outcome will be.
Please visit Introduction To The Maven Lifecycle reference guide for full details on all the maven lifecycle phases.
Command | Description | Notes |
---|---|---|
mvn clean | removes all the files created by the previous build | Usually means it deletes the contents of the modules */target/ directory. |
mvn validate | validates that the maven poms are all correct and that no config is missing | Usefull to run when making build modifications to ensure consistency. |
mvn compile | compiles the source code of the project | This will verify that project dependencies are correct. |
mvn test | executes the unit tests | Should not rely on code being packaged or deployed, only unit tests. |
mvn package | packages the code into the its distributable formats (jar, war, zip etc) | Each pom specifies what the distribution format is, default is POM. |
mvn verify | verifies that the packaged code is valid | This will run the integration and system tests. |
mvn install | installs the package into the local maven repository | This will result in the module being available, locally, as a depedency |
mvn deploy | copies the final artifacts to the remote maven repository for sharing | This would happen only when modules ready to be shared with other developers or projects |
mvn site:stage | creates a staged version of the maven site with all the reports | Staging output defaults to the */target/staging/ directory |
mvn jacoco:report | generates the code coverage report for the tests that have been executed | Test output appears in the */target/site/jacoco/ directory |
Maven Profiles
Maven profiles are used to allow set configuration to be enables easily at the command line using the -P option. If no profile is selected, java-mms-1.0 is run by default.
for e.g.
mvn verify -Pjava-bdb.1-0
Please visit Introduction To Maven Profiles for full details on the use of profiles in a maven build.
Profile Name | Description |
---|---|
java-store .protocol | Test profile to use AMQP protocol with store store for Java Broker for system testing. Store can be bdb , derby , json , mms the latter signifying a test in-memory store principally used for testing.Note that when running the older protocols, it is necessary to add the system property -DenableAmqp0-x to the command line. |
cpp | Test profile to use AMQP 0-10 and the C++ for system testing |
apache-release | Release profile for performing Apache software releases |
dependency-check | Dependency check to validate project licensing ahead of release |
joramtests | Profile used to execute the Joram JMS test suite (more below). |
tck | Profile used to execute the JMS TCK (more below) |
Maven Build Output
By default the build output for a maven module will appear in the modules "target" directory:
for e.g. the broker core module output appears in:
broker-core/target
Depending on the goals specified in the last build, one or all of the following can be found in the "target" directory.
Location | Description | Notes |
---|---|---|
*/target/ | Packaged build artifacts | JAR, WAS, ZIP etc as well as any release specific artifacts specified in assembly files i.e. release tars |
*/target/surefire-reports/ | Logs from unit/system test and Surefile summary | Logs files generated by the tests (named TEST-<test-class>-<test-method>.txt). Surefire summary has an .xml extension. |
*/target/qpid-broker/${project.version}/qbtc-test-config/ | Broker configuration used by the System tests | Broker configuration used by the System tests |
*/taget/site/ | Maven site output | Maven reports generated in HTML format i.e. test reports, code coverage etc |
*/target/staging/ | The staged maven site | Local attempt to generate the full maven site |
The releaseable Client and Broker binary packages can be found in the following locations locally if required for testing.
Broker
broker/target/qpid-broker-VERSION-bin.tar.gz
Once you have this then follow the Java Broker installation instructions.
Client
client/target/qpid-client-VERSION-bin.tar.gz
Once you have this then refer to the JMS client documentation.
Example Maven Commands
Here are some example Maven build commands that you may find usefull.
Clean previous builds output and install all modules to local repository without running any of the unit or system tests.
mvn clean install -DskipTests
Clean previous builds output and installs all modules to the local repository after running all the tests using the Java BDB 1-0 profile
mvn clean install -Pjava-bdb.1-0
Clean previous builds output and installs all modules to the local repository after running all the tests using the Java MMS 0-9 profile
mvn clean install -Pjava-mms.0-9 -DenableAmqp0-x
Perform a subset of the QA (int or sys tests) on the packaged release artifacts
mvn verify -Dtest=TestNamePattern* -DfailIfNoTests=false
Execute the unit tests and then produce the code coverage report
mvn test jacoco:report
Joram JMS Testsuite
The Joram JMS Testsuite is integrated into the Maven build but is disabled by default. It allows the Joram JMS test suite to executed, using the specified Qpid JMS client, against the Java Broker. The Java Broker must be running already.
The following clients are supported:
- qpid-jms-client - Qpid Client AMQP 1.0
- qpid-amqp-1-0-client-jms - the proof of concept Qpid Client AMQP 1.0 (development ceased 0.32)
- jms-client for AMQP protocols 0-8..0-10
To use the test suite, first configure the Java Broker to permit HTTP basic-authentication, then run the following command:
mvn -f joramtests/pom.xml integration-test -Djoramtests=<jms client identifier>
where <jms client identifier>
is one of: qpid-jms-client
, qpid-amqp-1-0-client-jms
, jms-client-0-9
, jms-client-0-10
.
The Maven failsafe plugin will run the tests. Unit output is produced in joram-tests/target/failsafe-reports
and the log from the client is written to joramtests/target/joramtest.log
.
To run a particular test use the failsafe plugin property -Dit.test:
mvn -f joramtests/pom.xml integration-test -Djoramtests=qpid-amqp-1-0-client-jms -Dit.test=ConnectionTest
JMS TCK
The configuration for the JMS TCK is integrated into the Maven build but the profile is disabled by default. The JMS TCK itself is proprietary and must be provided by the user. The Java Broker must be running and HTTP management available. The test suite will automatically set-up/teardown the JMS objects required by the TCK.
- qpid-jms-client - Qpid Client AMQP 1.0
- jms-client for AMQP protocols 0-8..0-10
To use the test suite, first unpack the JMS TCK into a directory, then invoke in the following way:
Code Block | ||||
---|---|---|---|---|
| ||||
mvn post-integration-test -Dtck=qpid-jms-client -f tck/pom.xml -Dtck.directory=/path/to/jmstck/ |
To run an individual test, use the tck.test
system property.
Code Block | ||||
---|---|---|---|---|
| ||||
mvn post-integration-test -Dtck=qpid-jms-client -f tck/pom.xml -Dtck.directory=/path/to/jmstck/ -Dtck.test=com/sun/ts/tests/jms/ee/all/sessiontests/SessionTests.java |
JMS 2.0 TCK can be run against Java Broker only with qpid-jms-client (for AMQP 1.0) by specifying profile jms20-tck and location of directory containing expanded TCK. For example,
Code Block | ||||
---|---|---|---|---|
| ||||
mvn post-integration-test -f tck/pom.xml -Pjms20-tck -Dtck.directory=/home/alex/tck/jmstck20 -Dqpid-jms-client-version=0.20.0 |
Performance Tests
The Performance test suite is integrated into Maven. It is bound to the integration-test phase and it is activated by the perftest
system property. The Java Broker must be running and HTTP management available. The test suite will automatically set-up/teardown the JMS objects required for the performance tests.
The following clients are supported:
- qpid-jms-client - Qpid Client AMQP 1.0
- jms-client for AMQP protocols 0-8..0-10
To invoke:
Code Block |
---|
mvn -f perftests/pom.xml integration-test -Dperftests=jms-client-0-9 |
Most things can be overridden from system properties. Take a look in the first few lines of the POM.
Python Tests
The Python Test suite runs against the Java Broker too but is not currently integrated into Maven. To run the 0-8..0-10 test suites use the following steps. It assumes that qpid-python
and qpid-cpp
are checked out.
Configure the Java Broker to allow so that the authentication provider permits plain connections.
Code Block curl --user admin:admin -d '{"secureOnlyMechanisms": []}' http://localhost:8080/api/latest/authenticationprovider/passwordFile
Install the Python packages to a suitable location.
Code Block LOCALROOT=~/myroot (cd qpid-cpp/management/python && python setup.py install --root ${LOCALROOT}) (cd qpid-python && python setup.py install --root ${LOCALROOT}) export PYTHONPATH=${LOCALROOT}/lib/python2.7/site-packages
Run the tests will the following command:
Code Block QPID_JAVA=/path/to/my/qpid-java cd qpid-python ./qpid-python-test -b amqp://guest/guest@localhost:5672 -I${QPID_JAVA}/test-profiles/python_tests/Java010PythonExcludes -I${QPID_JAVA}/test-profiles/python_tests/JavaPre010PythonExcludes -m qpid_tests.broker_0_10 -m qpid_tests.broker_0_9 -m qpid_tests.broker_0_8 -m qmf.console [<fully qualified test name>]
Todo. Describe the running of the AMQP 1.0 test suite using the swigged binding/proton-c. See the https://builds.apache.org/view/M-R/view/Qpid/job/Qpid-Python-Java-Test/.
IDE integration
Nowadays, most of the team chose IntelliJ.
IntelliJ
To setup the project, simply import the POM that resides at the top level.
Configuring the Annotation Processor
The build uses Java Annotation Processors to automatically generate code for things such as factories. Intellij's annotation processor defaults don't play nicely with Maven. A symptom of this is missing implementation classes when you try and start the Broker.
Go into "Preferences" -> "Annotation Processors"
- Ensure that the default profile includes all modules.
- Ensure that Enable Annotation Processing is ticked.
- Ensure that the Production Source Directory and Test Source Directory match that used by Maven. Choose Module Content Root and use the following paths.
target/generated-sources/annotations
target/generated-test-sources/test-annotations
- The option Obtain processors from project classpath does not seem to work. As a workaround, you may use Processor Path specify the path to the codegen's JAR
- /path/to/home/.m2/repository/org/apache/qpid/qpid-broker-codegen/6.2.0-SNAPSHOT/qpid-broker-codegen-6.2.0-SNAPSHOT.jar
This workaround does mean that you need to remember to mvn install
each time the codegen project is changed, and update the version number each time the version number bumps.
Running the Broker within Intellij
TODO expand on this.
You need to
- specify QPID_WORK and QPID_HOME in the "VM options"
- set the class path to "qpid-broker"
- set the working directory to the root source folder
- add dojotoolkit and bdb to the "qpid-broker" module dependencies
Running System Tests within Intellij
Running system tests from within IntelliJ requires a bit of fiddeling. You first create a template configuration which you then need to adapt every time you want to run a different systest. This means this method does not support running the entire test suite.
- Add a new Configuration
- "Run" --> "Edit Configurations..."
- Press the plus
sign at the top left to add a new configuration and select "JUnit"
- Change the name to "Systest"
- Add these to the "VM options"
- -Dprofile.virtualhostnode.context.blueprint='{"type":"ProvidedStore","globalAddressDomains":"${dollar.sign}{qpid.gloabalAddressDomains}"}'
- -DQPID_HOME=<your Qpid home path>
- -DQPID_WORK=<your Qpid work path>
- -Dqpid.globalAddressDomains=[]
- Change the "Working Directory" to point to your source root folder (i.e., the folder containing the systests folder)
- Set "Use classpath of mod..." to "qpid-systests"
- When you want to actually run a specific test, copy the fully qualified class name of the test into the "Class" field of this configuration before executing it.
If you are wanting to run the python tests against the broker you will of course need a version of python.
Build Instructions - Trunk
Our build system has reverted to ant as of May 2008.
The ant target 'help' will tell you what you need to know about the build system.
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.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 |
test | Runs the testsuite for Qpid |
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, 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 module e.g. to compile the broker source
Configuring Eclipse
1. Run the ant build from the root directory of Java trunk.
2. New project -> create from existing file system for broker, common, client, junit-toolkit, perftests, systests and each directory under management
4. Add the contents of lib/ to the build path
5. Setup Generated Code
6. Setup Dependencies
Generated Code
The Broker and Common packages both depend on generated code. After running 'ant' the build/scratch directory will contain this generated code.
For the broker module add build/scratch/broker/src
For the common module add build/scratch/common/src
Dependencies
These dependencies are correct at the time of writting however, if things are not working you can check the dependencies by looking in the modules build.xml file:
No Format |
---|
for i in `find . -name build.xml` ; do echo "$i:"; grep module.depends $i ; done
|
The module.depend value will detail which other modules are dependencies.
broker
- common
- management/common
client
- Common
systest
- client
- management/common
- broker
- broker/test
- common
- junit-toolkit
- management/tools/qpid-cli
perftests
- systests
- client
- broker
- common
- junit-toolkit
management/eclipse-plugin
- broker
- common
- management/common
management/console
- common
- client
management/agent
- common
- client
management/tools/qpid-cli
- common
- management/common
management/client
- common
- client
integrationtests
- systests
- client
- common
- junit-toolkit
testkit
- client
- broker
- common
tools
- client
- common
client/examples
- common
- client
broker-plugins
- client
- management/common
- broker
- common
- junit-toolkit
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.