Mercury Ant tasks – HowTo


December 18, 2008 By oleg

Mercury logomercury-ant-tasks is an Ant wrapper for Mercury functionality, that provides a lot of Mercury functionality inside ant scripts.

———–
Please check this posting first. It contains the latest information on the subject.
———–



What exactly is provided:

  • Configuration
    • named authentication elements to be used by repository or proxy authentication
    • supports both name/password or certificate pointer (file or URL) plus optional password
    • named repository configurations
    • local repositories (not limited to one)
    • remote repositories
    • stream verification per repository – separate for reading and writing
    • currently supported SHA-1 and PGP (.asc)
  • named dependency sets
    • lists dependencies and optionally – their Maven scopes
    • standardized on a one-string naming convention
    • supports OSGi-syntax version ranges
  • ant path creation/alteration
    • a task that either creates a new ant path or adds to existing one
    • optionally allows to specify Maven-like scope for the path resolution
  • repository writes
    • allows to write named files into repositories
    • optional classifiers, types
    • signature generation is configured per repository
    • SHA1, PGP

Where to get mercury-ant-tasks?

All the development releases will be deployed to this site; grab the latest snapshot and:

  • put it into ${user.home}/.ant/lib
  • if you plan to use PGP signatures – also put there bcpg-jdk15-140.jar and bcprov-jdk15-140.jar from this central repository location
  • if interested – my test build.xml contains all the unit test scripts

mercury-ant-tasks howto-by-example

  

This snippet shows how to define mercury namespace in the ant project markup

<project name="mercury-ant-test" default="compile"
xmlns:merc="antlib:org.apache.maven.mercury.ant.tasks" > ... </project>

  

This snippet shows how to define two repositories – one remote, one local. You don’t have to always define a local repository, but in this case binaries would reside in temp. location and will be reloaded from the remote on each invocation of the merc:resolve task

<merc:config id="conf">
  <merc:repo id="localRepo" dir="/maven.repo"/>
  <merc:repo id="central" url="http://repo1.maven.org/maven2"/>
</merc:config>

  

This snippet shows how to define authenticated repository and hide the password in the external file, so that each OS user can have their own credentials

<property file="~/.secret/secret.properties"/>
 
<merc:config id="conf">
  <merc:auth id="repo-auth" name="${repo.user}" pass="${repo.pass}"/>
  <merc:repo id="localRepo" dir="/maven.repo"/>
  <merc:repo id="central" url="http://repo1.maven.org/maven2"
             authid="repo-auth"/>
</merc:config>

  

This snippet shows how to configure a repository for PGP signature generation and checking; here secret keyring password is also kept in external file. Key ID always is a 16-digit hex number – use GnuPG GUI to look it up (and also generate/manipulate your keys). The verifier will accept any key from pubring.gpg for the signature

<property file="~/.secret/secret.properties"/>
 
<merc:config id="conf">
 
  <merc:auth id="repo-auth" name="${repo.user}" pass="${repo.pass}"/>
 
  <merc:repo id="localRepo" dir="/maven.repo"/>
 
  <merc:repo id="central" url="http://repo1.maven.org/maven2"
                    authid="repo-auth">
 
    <merc:verifywrite type="pgp">
      <property name="keyring" value="/home/me/pgp/secring.gpg"/>
      <property name="pass" value="${secret.keyring.pass}"/>
      <property name="key" value="0EDB5D91141BC4F2"/>
    </merc:verifywrite>
 
    <merc:verifyread type="pgp">
      <property name="keyring" value="/home/me/pgp/pubring.gpg"/>
    </merc:verifyread>
 
  </merc:repo>
 
</merc:config>

  

This snippet shows how to define authenticated repository and hide the password in the external file, so that each OS user can have their own credentials

<property file="~/.secret/secret.properties"/>
<merc:config id="conf">
  <merc:auth id="repo-auth" name="${repo.user}" pass="${repo.pass}"/>
  <merc:repo id="localRepo" dir="/maven.repo"/>
  <merc:repo id="central" url="http://repo1.maven.org/maven2"
                    authid="repo-auth"/>
</merc:config>

  

This snippet shows how to define a dependency set. Junit will only be added to paths that define scope=”test”

<merc:dep id="my-libs">
  <merc:dependency name="asm:asm:[2.0,3.0)"/>
  <merc:dependency name="junit:junit:[4.0.1,):::test"/>
  </merc:dep>

  

This snippet shows how to resolve a dependency set and add the resulting binaries to “compile-path” path. This path will not include JUnit from previous snippet

<merc:resolve pathid="compile-path" depid="my-libs" configid="conf" />
<javac srcdir="${src}" destdir="${target}" classpathref="compile-path" />

  

This snippet shows how to resolve a dependency set in test scope and add the resulting binaries to “test-compile-path” path. This path will have JUnit

<merc:resolve pathid="test-compile-path"
                      depid="my-libs"
                      configid="conf"
                      scope="test"
/>

  

This snippet shows how to write a jar file and it’s sources to a repository

<merc:write repoid="remoteRepo"
                   name="t:t:1.0"
                   file="${basedir}/target/t.jar"
/>
<merc:write repoid="remoteRepo"
                   name="t:t:1.0:sources"
                   file="${basedir}/target/t-src.jar"
/>

 


 

mercury-ant-tasks reference

Now, let’s have a closer look at ant mercury markup. To make it available to ant, provide a namespace definition on the project level, for example:
<project name="test" default="compile" xmlns:merc="antlib:org.apache.maven.mercury.ant.tasks">

Everywhere here I mention named – named configuration, named set. It means named in ant sense: something that has an id attribute value, and then we can reference that particular object (configuration, set, etc) by this value.

Tag Attribute
(required)
Description
merk:config defines a named configuration, for now it’s just a set of named repositories and authentications
id the name of this configuration
merc:auth defines a named authentication
id name of this authentication
user user name to use in this authentication
certfile a pointer to certificate file or URL. Can take a form of just a file pointer, or URL: file:///home/me/certificate. Or regular URL http://my.site.com/certificates/file. Note: currently SSL client does not support client certificates
pass password to use with either user or certificate
merc:repo defines a named repository that may contain dependencies. It can only reside inside merc:config element
id defines a unique id for this repository. Use consistent IDs as the are used by cache to speed up access to repository metadata
type repository type, used internally to find repository implementation. Default is M2 repository implementations from Mercury (default: “m2″)
dir defines a local repository. Point to the root of the local repository directory
url defines a remote repository and contains it’s URL
authid contains a reference to the merc:auth element that defines how to access authenticated repository
proxyauthid contains a reference to the merc:auth element that defines how to access authenticated proxy for a repository
readable boolean, defines this repository as suitable for reading from it
writeable boolean, defines this repository as suitable for writing to it
merc:verifyread defines a read verification configuration.It can only reside inside merc:repo element
type define the verification algo to use. Supported today are pgp and sha1
lenient boolean, if set to true – verification failure does not stop the repository operation (default: true)
sufficient boolean, if set to true and there are multiple verificators – success of this verification stops all others (default: false)
merc:verifyread defines a read verification configuration.It can only reside inside merc:repo element
type define the verification algo to use. Supported today are pgp and sha1
lenient boolean, if set to true – verification failure does not stop the repository operation (default: true)
sufficient boolean, if set to true and there are multiple verificators – success of this verification stops all others (default: false)
merc:deps defines a named set of dependencies
id the name of this set
merc:dependency a path element query, that could be resolved by merc:resolve task
name a query in the format groupId:artifactId:versionRange:classifier:type:scope, required are only the first 3 fields, the rest can be omitted. Examples: ant:ant:1.7.0 – search for this dependency, ant:ant:[1.7.0,) - search for any version, greater or eq. to 1.7.0, ant:ant:[1.7.0,)::test - search for these version and resolve them in the test scope (see merc:resolve), ant:ant:[1.7.0,1.7.1] – search for ant versions between 1.7.0 and 1.7.1 inclusive, my.apps:app:1.1::zip – find and store locally my.app/app/app-1.1.zip
merc:resolve ant path manipulation: create new path or append to the existing path
depid id of the dependency set that should be resolved and added to the path
configid id of the configuration to be used by this resolution
pathid id of the newly created path. This path should not have been previously defined
refpathid id of the existing path. This path should already exist
scope scope, for which this path should be resolved. (default: compile)
merc:write this task writes a file to the specified repository under specified name
repoid id of the repository to write this file into
name repository name of the atrifact to write to the repository (see dependency name desc., exclude ranges)
pom pom file to use instead of the name attribute
file file to be written to the repository