Apache Felix SCR Ant Task Use

Using the Apache Felix SCR Ant Task to generate Declarative Services and Metatype Service descriptors during an Ant driven Build.

The SCR Ant Task is implemented in the org.apache.felix.scr.ant library which must be registered as an Ant Task in the build file as follows:

<project ...>

    classpath="org.apache.felix.scr.ant-1.8.0.jar" />


Of course the value you set in the classpath attribute depends on the actual location of the org.apache.felix.scr.ant JAR file.

The SCR Ant Task is available for download from the Apache Felix Downloads page.


  • The name of the task is scr

  • The task requires that the source files have already been compiled

The task only generates the descriptor file(s). If you want to use the Declarative Services descriptor — by default generated in the OSGI-INF/serviceComponents.xml — you must make sure to add a Service-Components header to your bundle manifest. Unlike Maven plugin the Ant task cannot automatically generate this header.

Task Attributes

Like the standard javac Ant Task, the SCR Ant Task defines an implicit fileset which defines the source files to be scanned for Java 5 Annotations or JavaDoc Tags. In addition to the child elements available to Ant Fileset as defined for directory-based tasks the following task attributes are supported:

scrdir + Required: Yes + Default —  + The root directory of the implicitly defined fileset denoting the files to consider for annotation and/or JavaDoc tag processing.

destdir + Required: Yes + Default: —  + The name of the directory where the descriptor files are generated into. This is also used as the directory where the compiled classes from the srcdir may be located. This directory is actually added as another element to the classpath as defined by classpath and classpathRef.

classpath + Required: No + Default:  —  + The class path used to load classes from to analyse for the descriptor file generation. Generally this will be the same class path as the one used to compile the sources.

classpathRef + Required: No + Default: —  + A reference to a class path used to load classes from to analyse for the descriptor file generation. Generally this will be the same class path as the one used to compile the sources.

finalName + Required: No + Default: serviceComponents.xml + The name of the descriptor file to create. This file is always located inside the OSGI-INF folder in the destdir.

metaTypeName + Required: No + Default: metatype.xml + The name of the descriptor file to create. This file is always located inside the OSGI-INF/metatype folder in the destdir.

generateAccessors + Required: No + Default: true + If this switch is turned on, the bind and unbind methods for unary references are automatically generated by the plugin.

annotationTagProviders + Required: No + Default:  —  + List of fully qualified class names providing more Annotation Tag Providers. As of version 1.4.0 of the SCR Annotations library this configuration element is optional if the SCR Annotations library comes with a proper SPI setup (see link:{{ refs.extending-scr-annotations.path }}[Extending SCR Annotations])

specVersion + Required: No + Default: Auto-Detected + The plugin will generate a descriptor for the Declarative Service version (e.g. 1.0, 1.1, or 1.2). If no value is specified, the plugin will detect the version and only use 1.1 if features from this version are used.

strictMode + Required: No + Default: false + If set to true, a warning will be considered as an error and the build will fail with warnings generated by this task.

parseJavadoc + Required: No + Default: true + If set to true, JavaDoc based annotations will be processed.

processAnnotations + Required: No + Default: true + If set to true, SCR annotations will be processed

The scr task must be provided with the same class path as was used to compile the sources. The classes in the class path are used by the task to be able to load compiled classes (mostly for Java 5 annotation processing) and any base classes, which may be extended. The easiest way to share the class path is to define a class path property and refer to it with the classpathref attribute of the scr task.

Using JavaDoc Tags

JavaDoc tags are supported natively by the SCR Ant Task. No further configuration and/or libraries are needed.

Java 5 Annotations

To use Java 5 Annotations make sure the library defining the annotations is available on the class path for both the compilation in the javac task and for generating the descriptor in the scr task.

No further configuration is required as the SCR Ant Task automatically recognizes SCR Annotation definitions from libraries in the class path provided the annotations are provided in a JAR library with properly setup SPI configuration as documented in link:{{ refs.extending-scr-annotations.path }}[Extending SCR Annotations].


The following is very simple example build file based on the Apache Sling JCR WebConsole bundle:

<project default="scr" basedir=".">

  <taskdef resource="scrtask.properties"
      classpath="org.apache.felix.scr.ant-1.8.0.jar" />

  <target name="init">
    <property name="src" value="src/main/java" />
    <property name="classes" value="target/classes" />
    <property name="m2Repo" value="${user.home}/.m2/repository" />
    <path id="dependencies">
      <fileset dir="${m2Repo}">
        <include name="javax/jcr/jcr/1.0/jcr-1.0.jar" />
        <include name="org/apache/sling/org.apache.sling.jcr.api/2.0.6/org.apache.sling.jcr.api-2.0.6.jar" />
        <include name="org/apache/felix/org.apache.felix.webconsole/3.0.0/org.apache.felix.webconsole-3.0.0.jar" />
        <include name="javax/servlet/servlet-api/2.4/servlet-api-2.4.jar" />
        <include name="org/apache/felix/org.apache.felix.scr.annotations/1.4.0/org.apache.felix.scr.annotations-1.9.6.jar" />
        <include name="org/osgi/org.osgi.compendium/4.3.1/org.osgi.compendium-4.3.1.jar"/>

  <target name="compile" depends="init">
      <mkdir dir="${classes}" />
      <javac srcdir="${src}" destdir="${classes}" classpathref="dependencies" />

  <target name="scr" depends="compile">
    <scr srcdir="${src}" destdir="${classes}" classpathref="dependencies" />

  <target name="clean">
    <delete dir="target" />