facebook

Ant Tasks for Automated SDC Integration

Ant tasks are an extensible framework for automating builds. See more about Ant at http://ant.apache.org/. Automating these tasks is useful if you have a proprietary plugin, and you want to include the plugin as part of one or more packages managed through SDC.

Quick Start Example

This quick start example authenticates with the SDC delivery hub, loads a new library, cleans up old versions of the library, and then promotes all the packages in a delivery group.

<project default="promote">  
  <target name="promote">

    <!-- Register the custom Ant tasks provided by SDC -->
    <typedef name="sdc-login" classname="com.genuitec.delivery.anttasks.SDCLoginTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar" loaderref="sdc-classes"/>
    <typedef name="sdc-promote-package"
      classname="com.genuitec.delivery.anttasks.SDCPromotePackageTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar" loaderref="sdc-classes"/>
    <typedef name="sdc-import-library" classname="com.genuitec.delivery.anttasks.SDCImportLibraryTask"
     classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar" loaderref="sdc-classes"/>
    <typedef name="sdc-remove-library" classname="com.genuitec.delivery.anttasks.SDCRemoveLibraryTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar" loaderref="sdc-classes"/>

    <!-- Authenticate with the server -->
    <sdc-login host="sdc.example.com" port="1305"
    token="9195-a6bb-e0d4" passphrase="sdcphrase"/>

    <!-- Load the new version of our update site-->
    <sdc-import-library guidorname="ExampleSoftware" version="5.7.1"
   archivefile="/path/to/archive.zip"/>

    <!-- Delete old nightlies, keeping 3 for the testing team -->
    <sdc-remove-library guidorname="ExampleSoftware" numberofunusedversionstokeep="3"/>

    <!-- Promote our test packages -->
    <sdc-promote-package comment="Promote installers after new Nightly build"
   schedulebuild="true" deliverygroups="Nightly Group"/>  
  </target>
</project>

Installing the Tasks Jar

The JAR needed for these tasks can be downloaded from sdc-ant-tasks.jar found in sdc-ant-tasks.zip.

Save this JAR to a path on your build machine and remember the path for use in your <typedef> elements.

Defining the Tasks

To use the tasks, you must define them using the Ant typedef command. We suggest the following definitions, although it is possible to name them using your conventions.

<typedef name="sdc-login"
      classname="com.genuitec.delivery.anttasks.SDCLoginTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar"
      loaderref="sdc-classes"/>

<typedef name="sdc-import-library"
      classname="com.genuitec.delivery.anttasks.SDCImportLibraryTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar"
      loaderref="sdc-classes"/>

<typedef name="sdc-remove-library"
      classname="com.genuitec.delivery.anttasks.SDCRemoveLibraryTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar"
      loaderref="sdc-classes"/>

<typedef name="sdc-promote-package"
      classname="com.genuitec.delivery.anttasks.SDCPromotePackageTask"
      classpath="/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar"
      loaderref="sdc-classes"/>

<typedef name="sdc-build-pack"
      classname="com.genuitec.delivery.anttasks.SDCBuildPackTask"
      classpath="${sdc_ant_tasks_release}" 
      loaderref="sdc-classes" />

<typedef name="sdc-install-pack"
      classname="com.genuitec.delivery.anttasks.SDCInstallPackTask"
      classpath="${sdc_ant_tasks_release}" 
      loaderref="sdc-classes" />

<typedef name="sdc-update-package"
      classname="com.genuitec.delivery.anttasks.SDCUpdatePackageTask"
      classpath="${sdc_ant_tasks_release}" 
      loaderref="sdc-classes" />

<typedef name="sdc-remove-pack"
      classname="com.genuitec.delivery.anttasks.SDCDeleteSoftwarePackVersionTask"
      classpath="$/full/path/to/sdc-ant-tasks/sdc-ant-tasks.jar" 
      loaderref="sdc-classes" />

Using the Tasks: sdc-login

Before you make other requests in the course of a script, you must log into the delivery hub, or server. The sdc-login task allows you to create a session with the server. This session is necessary to allow you to modify artifacts that should be modified only by administrators of the system. Obtain a token from the SDC Admin Console’s System>Advanced tab to supply to this task in addition to the pass phrase used to generate the token.

Example:

<sdc-login
      host="sdc.example.com"
      port="1305"
      token="9195-a6bb-e0d4"
      passphrase="sdcphrase"/>

If you configured alternate web mappings for Ant & Build Web Services on the Advanced tab of the System Administration page, your login task should specify a URL instead of a host and port. The URL should match the web mapping defined on the System Administration page.

<sdc-login
      url="http://proxy.sdc/ws/build"
      token="9195-a6bb-e0d4"
      passphrase="sdcphrase"/>

Using the Tasks: sdc-import-library

Use the sdc-import-library command to automatically load the results of your build into SDC. If you have code signing enabled, you can wait for the signing to complete before proceeding; this ensures that promotions and builds you run later will use the signed versions of the artifacts.

You must define the first version of the library via the SDC Admin Console. Subsequent versions can be loaded using the Admin Console or the Ant task. Finally, the archive file is expected to be a ZIP file of an update site with the contents of the update site at the root of the archive.

Examples:

This example imports Checkstyle version 5.7.1 from the update, which has an installable unit ID of net.sf.eclipsecs.checkstyle.

<sdc-import-library
      guidorname="Checkstyle"
      versionfromiu="net.sf.eclipsecs.checkstyle"
      archivefile="/path/to/archive.zip"/>

The following example has the Ant task wait while the site is checked and potentially signed as part of import.

<sdc-import-library
      guidorname="Checkstyle"
      versionfromiu="net.sf.eclipsecs.checkstyle"
      archivefile="/path/to/archive.zip"
      waitforsigning="true"/>

The following example has the Ant task skip if the library exists.

<sdc-import-library
      guidorname="Checkstyle"
      versionfromiu="net.sf.eclipsecs.checkstyle"
      archivefile="/path/to/archive.zip"
      skipifexists="true"/>

Using the Tasks: sdc-remove-library

After a new library version is added, you might want to clean up older versions of that library to save hard drive space. The sdc-remove-library task allows you to clean up a specific version of a library or to limit the number of libraries kept in the system.

You cannot remove libraries that are in use by packages. For example, if you have a testing team that created a package referencing a library version from a build 10 days ago and you are creating nightly builds, that original library version will remain in the system until the testing team’s package is deleted or updated to reference a new version of the library. At this point, if you are using the numberofunusedversionstokeep attribute, this task will consider the library no longer in use and delete it (assuming you’ve continued loading nightly builds).

Examples:

To remove a precise library version:

<sdc-remove-library
      guidorname="Checkstyle"
      version="5.7.1"/>

If you don’t want to keep track of the versions loaded in your system, you can specify the number of unused versions you want to keep around. This example removes all but the latest three unused versions of the library.

<sdc-remove-library
      guidorname="Checkstyle"
      numberofunusedversionstokeep="3"/>

Using the Tasks: sdc-promote-package

After you have added or removed libraries, you are ready to promote packages that depend on those libraries. The sdc-promote-package task allows you to promote and optionally build packages. The comment you specify in the task definition is used as the promotion comment and is visible in the Admin Console and Portal. Like libraries, this task does not create new packages. New packages must be created using the Admin Console, and then they can be operated on via the Admin Console or the promote package Ant task.

All the following variations, with the exception of the packs variation, allow you to specify either the GUID or the title of an object as the parameter. You can determine the GUID by finding the file corresponding to the object in your <install>/DataFiles/metavc folder, but it’s often easier to use the title visible in the Admin Console.

If you promote with schedulebuild off, only the in-product promotion of the package will occur.

Examples:

To promote individual packages, use the comma-separated packages attribute:

<sdc-promote-package
      comment="Promote installers after nightly build"
      schedulebuild="true"
      packages="MyTeams Eclipse 3.7 Nightly,2319-dde-9882"/>

To promote all packages in one or more groups, use the comma-separated deliverygroups attribute:

<sdc-promote-package
      comment="Promote installers after nightly build"
      schedulebuild="true"
      deliverygroups="Nightly Auto-Build Group,1511-yuw-9843"/>

To promote all packages that require a specific Third Party Library, use the comma-separated libraries attribute:

<sdc-promote-package
      comment="Promote installers after nightly build"
      schedulebuild="true"
      libraries="Checkstyle,2343-efz-9882"/>

To promote all packages based on one or more software packs, use the comma-separated packs attribute. This attribute accepts the pack name as it appears in the UI or the pack id attribute from the root element of the pack.xml file of a particular pack version found in DataFilespacks.

WARNING: This could easily include all your packages.

This example promotes all Eclipse Discovery and MyEclipse Pro 10 based packages:

<sdc-promote-package
      comment="Promote installers after nightly build"
      schedulebuild="true"
      packs="eclipse-standard,myeclipse-pro-10"/>

Using the Tasks: sdc-build-pack

You can use the Software Pack Build task to build your own software pack installers. But, before jumping into building your own packs, you might need to work with your Genuitec support engineer for the initial setup of your pack source. Once you have your pack source, you can use this task to build it.

Example:

<sdc-build-pack
      id="myPackage"
      versioninternal="4.6.0" 
      versionpublic="2013.0.1"
      buildidproperty="pack-build-id" 
      packcontents=".." />

id: Corresponds with the ID of your new package.

versioninternal: The internal version of the software pack. Used for installing it.

versionpublic: The version visible to end users.

buildidproperty: The name of the property the build task will set with the value of the build ID. Each pack build done by the pack build task has a unique identifier that enables you to have the installers built by this task. The Package Update task (explained below) uses this property.

packcontents: Specifies the relative path where all the pack contents needed for the build are located.

When this task is executed successfully, the pack installers are built and located on the Delivery Hub under the directory Data Files/artifacts/packs. The installers are also available for download on the Portal from the URL http://<host>:<port>/admin/packs.

Using the Tasks: sdc-install-pack

You can automate the installation of software packs built using the Software Pack Install task. You can also use this task to install any pack on the Delivery Hub.

The Pack Build task discussed above set a property that can be used with this task to get the pack installer that was just built. To use this mode, you need to execute the Pack Install task during the same session as the Pack Build task.

<sdc-install-pack packbuildid=”${pack-build-id}” overwrite=”true”/>

Client-Side Example:

If you have the pack installer on the client side, the Pack Install task can upload the installer to the server to proceed with the installation.

<sdc-install-pack
      id="myPackage"
      versioninternal="4.6.0" 
      installerfile="/home/user/myPack-4.6.0.run"
      source="client" />

Server-Side Example:

If the pack installer is already on the server, you need only specify the path of the installer on the server.

<sdc-install-pack
      id="myPackage"
      versioninternal="4.6.0" 
      installerfile="/server/packs/myPack-4.6.0.run"
      source="server"
      overwrite="true" />

packbuildid: Normally, you won’t set this value manually. Instead, use the parameter set by the Pack Build task. When you built the installer using the task, you specified a parameter name. That name is the one to use as the value of this parameter. It is important to pay attention to the notation of the parameter: ${pack-build-id}.

overwrite: Specifies if you want to overwrite the pack install version if it’s already installed on the server. The value should be either true or false. This parameter is optional; if not specified, false is used by default.

id: The ID of the pack to install. This ID should match the ID in the installer’s pack.xml.

versioninternal: The version of the pack to install. This version should match the version in the installer’s pack.xml.

source: Denotes the location of the installer. The value should be either client or server.

installerfile: Provides the full path to the installer either on the client or on the server as specified by the source parameter. The install must be a Linux .run installer.

Notes:

  • If you specify the packbuildid, nothing else needs to be specified. SDC can get all the information from that parameter.
  • If no packbuild is specified, you must specify id, versioninternal, installerfile, and source.

Using the Tasks: sdc-update-package

You can automatically update packages on the Delivery Hub to use a specific software pack or library version. This task only changes the pack or library version already in use by this package. This task would commonly be used when you build and install packs automatically or when you load libraries automatically. With this task, you specify the packages to be updated to the specified software pack or library version. This task only commits the packages with the updated software pack or third-party library version. You can follow this task with the Package Promote task to promote the updated packages.

Examples of a few update combinations:

Update specific packages to a software pack version:

<sdc-update-package
      packages="Eclipse for Web Development,2319-dde-9882"
      comment="${comment}"
      packid="myPackage" 
      packversion="4.6.0" />

Update packages which use specified software packs to a software pack version:

<sdc-update-package
      packs="eclipse-standard"
      comment="${comment}"
      packid="myPackage" 
      packversion="4.6.0" />

Update packages which use specified third-party libraries to a software pack version:

<sdc-update-package
      libraries="Checkstyle,2343-efz-9882"
      comment="${comment}"
      packid="myPackage" 
      packversion="4.6.0" />

Update packages associated with specified groups to a third-party library version:

<sdc-update-package
      deliverygroups="Nightly Auto-Build Group,1511-yuw-9843"
      comment="${comment}"
      libraryid="Checkstyle" 
      libraryversion="1.2.3" />

packages: Specifies the packages to be updated. The value is a list of comma separated package IDs or package titles.

packs: The packages using the software packs specified here are updated. The value is a list of comma separated software pack IDs.

deliverygroups: The packages associated with the delivery groups listed here are updated. The value is a list of comma separated delivery group titles or IDs.

libraries: The packages using the specified libraries are updated. The value is a comma separated list of third-party library titles or IDs.

comment: The comment used during promotion.

packid: The ID of the software pack to which you want the packages to update.

packversion: The version of the software pack to which you want the packages to update.

libraryid: The ID or the title of the third-party library to which you want the packages to update.

libraryversion: The version of the third-party library to which you want the packages to update.

Notes:

  • To filter packages, you can use all or only one of the following parameters: packages, packs, deliverygroups and/or libraries.
  • You can specify both the third-party library ID and version and the software pack ID and version to update the packages to. But only one ID and version pair is required.

Using the Tasks: sdc-remove-pack

Use this custom task to remove a software pack from the SDC Hub. Required fields are pack id and pack version.

<sdc-remove-pack
      id="popular-pack"
      version="2013.2.0"/>