Platogo Blog

Managing source code dependencies is a burden you are confronted with in nearly every project in your daily life as a developer.

There are different strategies how to solve this dilemma. I´ll give it another try and will show you how you can overcome all this problems in ActionScript 3 projects through the usage of Apaches Ivy.

The Problem

Virtually every software relies on one or another library. This can be the flex framework, papervision3D or one of your company´s internal libraries. The more projects your application depends on the more complex the build process will get.

But you probably think:

We managed this dependencies in all our previous ActionScript projects already. Why do we have to make it again and again more complicated?

The Solutions?

You have probably solved it in one of the following ways:

1. Placing all dependent projects (JAR(SWC) files) in a directory that´s checked into the projects version-control repository. This technique bloates the repository unnecessarily, making it difficult to manage version differences.
2. Allocating dependent JARs(SWCs) to a common file server, which prevents the team from controlling version changes
3. Copying JAR(SWC) files manually to a specific location on each developer´s workstation. This approach makes it difficult to determine missing files or correct versions.
4. Performing an HTTP Get to download files to a developer´s workstation, either manually or as part of the automated build. This technique requires duplicate scriptlets and often leads to unmanaged JAR(SWC) files

Techniques taken and modified from Paul Duvall´s article "Automation for the people"
Changes are highlighted and put into brackets (Changed Content)

In all our applications in my former company we used the first technique, which went pretty fine so far. But during my last project there it got more complicated. We were developing smaller modules already, while improving the core frameworks, util libraries and so on. During this process it became more and more time consuming and confusing to keep all projects up-to-date.

Just a few dialogue examples:

Library developer: "Hey guys, I just fixed a few errors in the BlaBla class please update your util library."

There are four smaller projects going on at the same time and every project is being updated. A few minutes later.

Another developer: "Damn, I´ve to roll back the library, because now my application is broken, but I need the other fixes from the *** class. When did you check in the other change into subversion?

Library developer: "Hmmm. I don´t know if I´ve entered a svn-comment for this change. Can´t you just use your old version?"

Five hours later.

Library developer: "Hey guys, I missed a bug in the latest check-in, could you please update your util library again?"

Another developer: "What the ******!"

So dependency management is also a way to keep your collegues happy .

Apache Ivy

In next part of this article I´ll explain how to set up your own ivy repository and how to integrate it easily into your development process.

At the end of the article you will find three FlexBuilder projects using ivy to play around with.

Now there are also three FDT projects ready for download

One library project without dependencies, one library project with dependencies and one application which uses this two libraries.

Following parts are taken from Paul Duvall´s article "Automation for the people" and are modified and extended for ActionScript 3 development.

Getting started

Getting started with Ivy is as simple as creating two Ivy-specific files and adding a few Ant targets. The Ivy-specific files are ivy.xml and an ivysettings.xml file. The ivy.xml file is where you list all of your project's dependencies. The ivysettings.xml file (you can name this file anything you wish) is where you configure repositories that the dependent SWC files will be downloaded from.

For all following listings you will need for execution: Apache Ant standalone or use Eclipse with Ant support. The last one is the most common setup you´ll use if you are using FlexBuilder or FDT for ActionScript 3 development.

Listing 1 shows a simple Ant script that calls two Ivy tasks: ivy:settings and ivy:retrieve:

Listing 1. Simple Ant script using Ivy
<target name="resolve" depends="load-ivy">
<ivy:resolve file="${build.dir}/ivy/ivy.xml"/>
<ivy:retrieve />
</target>
In Listing 1, ivy:resolve resolves the dependencies and is normally called by ivy:retrieve automatically. In this case I defined it manually because I wanted to use a specific path to the ivy.xml. The call to ivy:retrieve retrieves the SWC files from one of the repositories declared in ivy.xml.

Installing Ivy

You have a couple of options for downloading and using Ivy. The first is to download the Ivy JAR file manually to your Ant lib directory or to a different directory that you define in your Ant script's classpath.
Even it would be easier to use for the first time to automaticaly download ivy, I downloaded it manually and placed it into a directory in my project (e.g. libs).

Download Apache Ivy - Beta 2.

Listing 2 shows an example how to use Ivy in your build file:
<project name="Ivy Library" xmlns:ivy="antlib:org.apache.ivy.ant">
<property name="ivy.jar.dir" value="${basedir}/libs" />
<target name="load-ivy">
<path id="ivy.lib.path">
<fileset dir="${ivy.jar.dir}" includes="*.jar"/>
</path>
<taskdef resource="org/apache/ivy/ant/antlib.xml"
uri="antlib:org.apache.ivy.ant" classpathref="ivy.lib.path"/>
<ivy:settings file="${ivy.settings.dir}/ivysettings.xml" />
</target>
The first line in Listing 2 defines the XML namespace.
The ivy.jar.dir value is the location where the ivy.jar file is placed. The taskdef defines the ivy Ant task, referring to its classpath location. The ivy:settings defines the Ivy settings file.
The ivy.xml file, where you define all of your project's dependent SWCs, is required.
Listing 3 shows an example:

Listing 3. Defining dependencies in ivy.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>
<ivy-module version="1.0">
<info organisation="com.metadudes" module="components" />
<dependencies>
<dependency org="com.metadudes" name="utils" rev="latest.integration" />
<dependency org="com.metadudes" name="commons" rev="1.9.1" />
</dependencies>
</ivy-module>
Notice that Listing 3 includes no indication of file locations or URLs, letting you move to different repository locations without needing to change the list of dependencies. The organisation attribute in the info element identifies the organization type (such as .net, .org, or .com). This is followed by the module name. The list of dependencies for this module follows a naming convention that will become more clear in the next listing. For now, just remember that dependency name="commons" rev="1.9.1" translates to commons-1.9.1.swc.

Listing 4. Creating your own library
<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="http://ivyrep.jayasoft.org/ivy-doc.xsl"?>
<ivy-module version="1.0">
<info organisation="com.metadudes" module="core" />
<publications>
<artifact name="core" type="swc" ext="swc" />
<artifact name="components" type="swc" ext="swc" />
<artifact name="commons" type="swc" ext="swc" />
</publications>
</ivy-module>
If you want to deploy your own module which consists of three swc files, just define in the artifact elements type and ext (extension) as swc. If you want to publish a new library to your network repository just call the ivy:publish task and it will do the magic for you as you see in Listing 5.

Listing 5. Publish your own library version to the repository
<target name="publish" depends="swc" description="publishes library">
<ivy:publish artifactspattern="${binRelease.dir}/[artifact].[ext]"
resolver="projects"
pubrevision="1.2
status="release"
/>
</target>
Listing 6 is an example of a Ivy settings file. It defines the repository locations and associated patterns used in the ivy.xml file in Listing 3.

Listing 6. Ivy settings file
<ivysettings>
<properties file="${ivy.settings.dir}/ivysettings.properties"/>
<settings defaultResolver="projects"/>
<caches defaultCacheDir="${ivy.settings.dir}/ivy-cache" />
<resolvers>
<filesystem name="projects">
<artifact pattern="${repository.dir}/[organisation]/[module]/[revision]/[artifact]-[revision].[ext]" />
<ivy pattern="${repository.dir}/[organisation]/[module]/[revision]/ivy.xml" />
</filesystem>
</resolvers>
</ivysettings>
The filesystem element in Listing 6 defines the location pattern on your local workstation or network-share. You could also add multiple locations the SWC file can be downloaded from. If Ivy is unable to download from the first repository — if it's down, for example, or if the file isn't in the specified location — it tries the next one. The beauty is that once Ivy downloads a SWC, it puts the file on your local file system so that it doesn't need to download these files for every build.

Depending on dependencies

It's typical for a module to have dependencies on other modules. Without a tool like Ivy, you would need to ensure the correct versions of all SWCs are in the classpath and that no conflicts exist among SWC versions. With Ivy, you simply define the myLibrary module and all of its dependent modules, as shown in the example ivy.xml file in Listing 7.

Listing 7. Defining dependencies in ivy.xml
<ivy-module version="1.0">
<info organisation="com.metadudes" module="myLibrary" />
<publications>
<artifact name="mylibrary" type="swc" ext="swc" />
</publications>
<dependencies>
<dependency org="com.metadudes" name="core" rev="latest.integration" />
<dependency org="com.metadudes" name="components" rev="1.2" />
</dependencies>
</ivy-module>
The highlighted dependency in Listing 7 defines the core module from com.metadudes along with the information to use the latest revision. Ivy uses this information along with the repository definitions in the ivysettings.xml file (as shown in Listing 6) to download the SWC file dependencies.

Figure 1. Possible ivy repository structure

In Figure 1 you see two modules (extendedhelloworld, helloworld) from organisation com.metadudes. Of module extendedhelloworld only one version is existing, whereas two versions of module helloworld are available. For more detailed information on the files in the version directory please use the ivy documentation.

Growing with Ivy

Now that you have the basics of using Ivy, I'll go over some other useful Ant tasks.

Rendering reports

Ivy provides a task for reporting the dependent files in a project. Listing 8 demonstrates calling Ivy's report Ant task to create a list of dependencies:

Listing 8. Generating an Ivy dependency report from Ant
<target name="ivy-report" depends="init-ivy">
<ivy:report todir="${basedir}"/>
</target>
An HTML report generated by the script in Listing 8 displays a list of the project's dependent files. Figure 2 shows the report:

Figure 2. HTML report showing project dependencies

See Resources to learn about other Ant tasks available in Ivy

It all depends

Versioning binaries

Paul Duvall´s final thoughts on this topic:

Ivy does not obviate the need to version-control JAR(SWC) files. I've often seen that teams provided with an HTTP-accessible repository forget to place the files in a version-control system at all. If you need to recreate the software a year from now and your HTTP repository isn't centrally managed, it could be extremely difficult to do so. Using an HTTP-accessible version control repository such as Subversion makes this less of a burden because you can manage centrally and provide HTTP access.

Ivy centralizes dependent files and reduces the bloat that can occur when development teams copy JAR(SWC) files from one version-control repository to the next. If you're working a simple project, it probably won't slow you down too much to check in JAR(SWC) files to your version-control system or use some of the other techniques I listed at the start of this article. But as your project gets larger or if you work in an enterprise environment that uses common files, a common approach becomes necessary. In either case, Ivy makes defining project dependencies more consistent and approachable, so it's worth your time to investigate the use of Ivy in your projects.

Paul Duvall - Changes are highlighted and put into brackets (Changed Content)

I´m right now in the process of integrating ivy into our buildprocess. It worked for me so far very well and I will post the outcome and best practice in one of my following posts. As Paul Duvall already mentioned its absolutly worth your time to investigate into Apache Ivy. So don´t waste to much time and get your hands on it right now.

Download Flex Projects using Ivy:

Download ivy settings
Download ivy library project
Download ivy dependent library project
Download ivy project

Download FDT Projects using ivy:

Download ivy settings
Download ivy library project
Download ivy dependent library project
Download ivy project

For the ivy dependent library project using FDT you have to add the resolved swc files manually into your classpath to prevent editor errors.

Installation instruction for FlexBuilder / FDT users:

Please make sure that Ant is already installed and configured in FlexBuilder.

1. Download and unzip the files to your local computer
2. Put the ivy settings directory somewhere on your hard drive, where you also want to place your local ivy cache (e.g. C:\dev\ivy\settings).
3. Open the file ivysettings.properties in the ivysettings folder and set your desired ivy repository path
   (e.g. repository.dir=I:/repository)
4. Open FlexBuilder and import IvyDependentLibrary, IvyLibrary and IvyProject projects
5. Open the build.properties files of each project and adapt the path settings
   (e.g. ivy.settings.dir=C:/dev/ivy/settings)
6. Drag the build.xml files of each project into the Ant window of eclipse
7. Run the IvyLibrary publish target
8. Run the IvyDependent Library publish target
9. Run the Ivy Project run target

All Ant targets also work with the Flex SDK only.

This projects should give you a first impression, what you can do with Ivy. For further investigations I recommend the examples on the ivy page.

Learn

• Apache Ivy: Visit the Ivy project site for documentation, tutorials, and community resources.
• Ivy / Maven2 Comparison (Apache Ant Ivy Project): A discussion of the differences between Ivy and Maven 2 dependency management.
• Automation for the people (Paul Duvall, developerWorks): Read the complete series.

Get products and technologies

• Ant: Download Ant and start building software in a predictable and repeatable manner.
• Ivy: Download Ivy.

Tags: Apache Ivy, Dependency Management

This entry was posted on Wednesday, November 12th, 2008 at 10:56 am and is filed under Adobe, Development. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.