This article describes the Artifactory integration in Ant build scripts, with the Apache Ivy library.

Some basic terminology

Apache Ivy (or just Ivy) is a generic library for integrating Ant with various dependency resolution and distribution systems; it is mostly used to access the Maven repository, but other options are available (including its "native" Ivy format). This is also reflected by different terminology that Ivy uses.

The build scrips of the censhare Server are written to generate Maven artifacts, with the following mapping concepts:

  • module: represents a Maven artifact, where the module name is the Maven artifactId. This mapping is achieved by publishing exactly one jar artifact per module.
  • organization: Maven artifact group
  • revision: version

3rd-party libraries

In the current state, all libraries used by censhare-product are stored directly in git, alongside sources. Newer applications use the standard Maven dependency declaration instead, downloading all required libraries from the repository (in our case, Artifactory).

To make sure that all libraries used by the code in censhare-Server are available in the Artifactory, the following special build target uploads all the libraries to the Artifactory: censhare Web :: 3rdparty-lib upload to artifactory

This job is implemented by target ivy.3rdparty-libs in build.common.xml and expects that the 3rdparty-libs/ivy/ directory contains an ivy file for each library.

Upgrading a library version

  1. Remove the old jar file and add a new jar file in the 3rdparty-libs directory. Please make sure to keep the same naming pattern as before with the only change being the version number. For example:
    • Old jar: 3rdparty-libs/guava-18.jar (removed)
    • New jar: 3rdparty-libs/guava-22.jar (added)
  2. Find the library usage in build.xml and fix the version number.

  3. Change the version (revision attribute) in the ivy file 3rdparty-libs/ivy/name-ivy.xml. Please mind that without this change, the TeamCity job will fail. For example: 3rdparty-libs/ivy/guava-ivy.xml should look like this:

    <ivy-module version="2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://Ant.apache.org/ivy/schemas/ivy.xsd">
  <info organisation="static.guava" module="guava" revision="22.0"/>
  <publications>
    <artifact name="guava" ext="jar"/>
    <artifact type="pom" ext="pom"/>
  </publications>
  <dependencies/>
</ivy-module>

Adding a new library

  1. Add the new jar file into the 3rdparty-libs directory and always use the standard pattern: name-version.jar. This pattern is already used in the absolute majority of libraries.
  2. Create an ivy descriptor file in the 3rdparty-libs/ivy directory:
    • The file name is derived from the library name by adding -ivy.xml (e.g. guava-ivy.xml).
    • To create its content, just copy one of the existing files and replace all occurrences of old library name and version (revision) with the details of the new library.
    • The details of the file format are described in Ivy documentation, but this is usually not needed.

censhare artifacts

Libraries created by the build in censhare-LibSupport and censhare-Server are automatically uploaded to the Artifactory by the standard Server Build job in TeamCity, implemented by the target ivy in the build.xml.

All published libraries have the com.censhare.lib Maven group and the artifactId is the same as the full library name (e.g. censhare-base, censhare-db, etc). The Version is derived from the censhare-product version and depends on several factors:

  1. If the property buildserver.build.counter is set, then the final version has the form <censhareVersion>-b<buildserver.build.counter>. This is used by the release builds.
  2. If the vcsroot.branch property is set and it does not end with /develop, the version has the form <branchname>-SNAPSHOT. The branchname is cleaned up by replacing all invalid characters with underscores. This is used by the various branch builds.
  3. Finally, if the version is <censhareversion>-SNAPSHOT, then this is the latest build from the develop branch.

Example of an artifact in the Artifactory: com.censhare.lib:censhare-base (library with basic censhare classes)

Warning: All the links above require authentication!