Omero Build System

Build-Tools

Starting with Omero 3.0-Beta3, the build system is based on ant (http://ant.apache.org) with dependency management via Ivy (http://ant.apache.org/ivy). Much of the build, however, is still influenced by early versions which used maven (http://maven.apache.org).

Structure of the build

This is an (abbreviated) snapshot of the structure of the filesystem for OMERO:

  OMERO_HOME
  |--build.xml
  |--etc/
  |   |-- ivyconf.xml
  |   |-- hibernate.properties
  |   |-- jndi.properties
  |   |-- local.properties
  |   |-- log4j.properties
  |   |-- omero-ds.xml
  |   |-- omero.properties
  |   `-- profiles
  `components
    |--<component-name>
    |    |--build.xml
    |    `--ivy.xml
    |--tools
    |    |--build.xml
    |    |--<tool-name>
    |         |--build.xml
    |         `--ivy.xml
    `--antlib
        `--resources
            |--global.xml
            |--directories.xml
            |--lifecylce.xml
            |--depdendencies.xml
            |--multiproject.xml
            `--server.xml

The build has basically three important components:

• A central set of files that are responsible for controlling the build. These files live in the root of the project: *build.xml: The top-level control of the build. The file checks pre-requisites for the build and calls targets on each individual component (similar to maven's "lifecycle" concept). This is done by importing antlib/resources/multiproject.xml. *etc/ivyconf.xml: Defines the resolvers which are used by Ivy to find the dependencies listed in the various ivy.xml files. *etc/*.properties: configuration files. local.properties contains properties tailored to the local environment and does not live in svn, but rather is generated by the setup target and copied by the build into the component directories.

• antlib: Contains common build-scripts and definitions that are used by every component and the top-level build. The files are:
  • global.xml: Central configuration used by any ant build script.
  • directories.xml: Contains common directories and directory-structures. If you are looking for a template of how to set up the directory-structure of a new component and where to find things in existing components, this is the place to look.
  • lifecylce.xml: All components share a common lifecycle - this lifecycle and the dependency between each lifecycle-step is defined here.
  • multiproject.xml: Allows the top-level build to apply the lifecycle across all components and tools in the proper order.
  • dependencies.xml: Uses ivy.xml files to define the order between the various components and permits the simple lookup and publishing of artifacts.
  • See the other files for more information.

• Every component has a separate build, that can be triggered standalone or from the central build (using the iterate macro). A component's build consists of the following scripts:
  • build.xml: If you have a simple component, that requires no specialized tasks, this file is merely used to import the proper files from antlib/resources and to hook into the common lifecycle.
  • ivy.xml: Contains dependencies that are special to this component.

Comments on Ivy

• Resolvers are key to how Ivy functions. Currently, the default resolver is called "omero-resolver" and simply looks in our repository (./lib/repository) for the jars which were downloaded from subversion. Multi-resolvers can be defined (as granular as for an individual jar) in order to pick up the latest version of whatever library from HTTP, SSH, or from the local file system.

• OMERO_HOME/lib/cache : in order to determine the transitive closure of all dependencies, Ivy "resolves" each ivy.xml and stores the resolved ivy.xml in its cache (in our build, ./lib/cache) to speed up other processes. However, when changing the Ivy configuration (./etc/ivyconf.xml) or version number (etc/omero.properties->omero.version) the cache can become stale. This should not happen, but currently does. It may be beneficial for the time being to call ant clean from the top-level build which will delete the cache.

Final products

All final products which act as servers, i.e. entry points to secure areas, must permit the hard-coding of security and licensing. Currently only components/app and components/blitz meet this criterion.

components/app

components/blitz

components/tools

Creating binary distribution

The "java omero dist" task will build the OMERO system and copy the necessary components for a binary distribution to the /dist directory. Below is a comparison of what is taken from the build, where it is put, and what role it plays in the distribution.

OMERO_HOME	OMERO_HOME/dist	Comments
components/app/target/omero-<version>.ear	omero-<version>.ear	The main application file
components/blitz/target/standalone	blitz/	Standalone Ice server, runnable via "java -jar blitz.jar"
etc/	etc/	Configuration
components/common/target/generated/resources/*.sql	sql/	SQL scripts to prepare the database
omero.class	omero.class	The build tool ("java omero ...")
components/antlib	components/antlib	Build scripts
components/antlib/resources/omero.xml	build.xml	Specialized top-level build script for the distribution
lib/repository/<some>	lib/repository	Libraries needed for the build
lib/repository/<some>	client/	Libraries needed by clients
<javadoc/>	docs/api	(Optional) Javadocs produced with "java omero javadoc"

These files are then zipped to omero-<version>.zip via "java omero zip"