Contents

1. Obtaining the sources
2. Project structure
3. Properties
4. build.properties
5. Third party dependencies
6. Building the sources
7. Versioning
8. Eclipse
9. Release

Obtaining the sources

There are 2 basic ways of obtaining the sources:

1. Fetch HEAD or some tag of jbpm.3 from the repository. In this case, you get one fixed set of versions for all subprojects. Typically all HEAD during development.
2. Second option is still TODO. This will be a script in which you will be able to configure sub project tags. For each project a separate CVS tag will be fetched. The source structure will however be the same as if you would fetch the complete jbpm.3 module.

Project structure

Module jbpm.3 contains several subprojects:

• bpel : the WS-BPEL runtime engine.
• console : the jBPM (currently only jPDL) console web application.
• designer/jpdl : the graphical designer for jPDL
• enterprise/cmdlistener : the command listener MDB
• enterprise/cmdservice : the command service SLSB
• enterprise/ear : the enterprise archive packaging
• identity : the identity module storing users, roles and organisational data
• jboss/configuration : configuration for and deployment to JBoss of jPDL
• jboss/db : building the default hsqldb db with jPDL tables and the example
• jpdl/db : jPDL SQL scripts generation
• jpdl/dist : building the jPDL runtime and suite
• jpdl/examples : the collection of example projects
• jpdl/jar : the jPDL jar library
• jpdl/userguide : the jPDL user guide

Each project has got its own build.xml build file. Apart from that, there is a general build.xml that has overall clean and build targets.

The build scripts are all by default fetching their jBPM dependencies in the source directory structure. Module jbpm.3 in jbpm CVS is considered the root directory. Default navigation for dependencies is done relative.

There are two types of projects:

• Artifact projects that produce exactly 1 artifact (e.g. identity, jpdl/jar, jpdl/db, ...)
• Module projects that group a number of child projects (e.g. jpdl, jboss, enterprise)

The structure of the artifact projects is inspired by maven. Yet still we think it is easier and more convenient for the jbpm developer community to keep ant as the central build system.

Properties

Sub project build files include properties files in the following order:

1. ${user.home}/jbpm/build.properties : This properties file can be used to customize build properties for your environment. Since this is located outside of the source structure, it will survive CVS updates.
2. build.properties located in the specific subproject directory.
3. ${jbpm.root}/build/build.properties is located in this directory and contains most of the default property values.

build.properties

Summarizing, ${jbpm.root}/build/build.properties in this directory will specify all the default properties that can be overwritten in the other two properties files mentioned above.

The general build.properties has 3 major sections:

• Homes: some targets have dependencies on (or produce) installed software. See inside the properties file (or use IDE search) for more details on which targets actually use the home properties.
• jBPM dependency properties: A set of properties that define where jBPM dependencies are resolved. Both for inclusion in the classpath and in packaging composite files.
• Third party dependencies: A set of third party library properties that reference third party libs in the local repository. The properties are structured in such a way that the version can be easily updated.

Property jbpm.root should be specified before ${jbpm.root}/build/build.properties is loaded. It must reflect a relative reference to the jbpm.3 module root directory.

Property module.name is optional. It is used to define properties artifact.id (as jbpm-${module.name}) and artifact.name (as jbpm-${module.name}.jar).

Third party dependencies

All third party dependencies are resolved from a local repository. By default the location is ${user.home}/jbpm/repository

In this directory, ant get.dependencies will fetch the jbpm required libraries from the jboss repository and puts it in your local repository.

The local repository is a subset of the remote repository. The remote repository is http://repository.jboss.com and can be accessed via http and an ordinary web browser.

The configuration properties for customizing the repository are specified in ./build.properties and can be overwritten in your ${user.home}/jbpm/build.properties. By default, the local repository will be ${user.home}/jbpm/repository. The property 'local.repository' specifies the absolute path of your local repository and the 'lib.xxx.version' property specifies the version for library xxx.

Adding a dependency to the repository

1. Find the library in http://repository.jboss.com
2. Find 'EXTERNAL DEPENDENCIES (1/4): VERSIONS' in ./build.properties and add the version dependency for your library.
3. Find 'EXTERNAL DEPENDENCIES (2/4): REPOSITORY LOCATION PROPERTIES' in that same ./build.properties and add the local and remote repository locations similarly as is done for the other libraries.
4. Find 'EXTERNAL DEPENDENCIES (3/4): BUILD CLASSPATH' in ./base.project.build.xml and add the library to the default build classpath.
5. Find 'EXTERNAL DEPENDENCIES (4/4): UPDATE LOCAL REPOSITORY' in ./build.xml and add the library to the 'get.dependencies' target.

One other special third party dependency is docbook-support. docbook-support is a module from the jboss cvs repository that is only used in building the jPDL docs. This is also required to build a distribution. The target to get the docbook-support module from cvs and put it in the local repository is get.docbook.support in the build.xml file in this directory.

For running the unit and coverage tests, JUnit and Clover need to be in the ant lib directory. In order to get them there, it is sufficient to get the thirdparty dependencies, verify the ant.home property in build.properties and run the target install.ant.libs in the build.xml in this directory. That target will copy the junit and clover libs from the local repository to the ant lib directory.

Versioning

Each top level module (e.g. console, enterprise, identity, jpdl, ...) has a version.

The version of the artifacts that are being produced is defined in the version.properties file located in the module directory. E.g. jpdl/version.properties

The version of the jbpm artifacts that is being used to build other jbpm artifacts is defined in the build/build.properties. Section JBPM ARTIFACT REFERENCES

Eclipse

To get the build path right in your eclipse environment, you need to set the JBPM_REPO class path variable to your local repository. To set your classpath variable, navigate: 'Window'-->'Preferences'-->'Java'-->'Build Path'-->'Classpath Variables'

You can import the jbpm.3 module as an eclipse project.

As an alternative, you can also import a subset of the directories in the jbpm.3 module as eclipse projects.

Release

Please, refer to the release guide in the wiki for release instructions.