Documentation (2.1.0)

IvyDE is the Eclipse plugin which integrates Ivy into your java development enviromnent. A summary of the features it provides follows: IvyDE can be also used with other plugins like WTP and Ant.

Release Notes

1. What is Apache IvyDE?
2. Status of this release
3. Major Changes in this Release
4. Committers and Contributors for this release
5. List of Changes in this Release


What is Apache IvyDE?

IvyDE is the plugin which integrates Ivy into Eclipse.

IvyDE lets you manage your dependencies declared in an ivy.xml in your Java
Eclipse projects. IvyDE will contribute to the classpath of your Java project or
you can make it retrieve your dependencies directly into your project. Last but
not least, IvyDE offer editors of ivy.xml and ivysettings.xml files with completion.

Status of this release

This is the second release of IvyDE hosted by the Apache Software Foundation.

Major Changes in this Release

Several new features have been added to enhance the developer's experience developing on multi-module interdependent applications,
including better support for the resolve in workspace feature, a new context menu in the package explorer, the Reverse Dependency Explorer.

The classpath container is now more tightly integrated its underlying ivy.xml resource and the launch configuration, and allows for more fine-grained
user control of these behaviors.

Committers and Contributors for this Release

Here is the list of people who have contributed source code and documentation
to this release. Many thanks to all of them, and also to the whole IvyDE community
contributing ideas and feedback, and promoting the use of IvyDE. The list would be too
long, but IvyDE couldn't be what it is without you!

Committers
Maarten Coene
Xavier Hanin
Nicolas Lalevee
Gilles Scokart
Jon Schneider

Contributors
Troy Gaines
Miguel Griffa
Adam Karl
Ivica Loncar
Sebastien Moran
Phillip Webb

For the list of people who have contributed since IvyDE inception, see CHANGES.txt file.

List of Changes in this Release

For a full release history of IvyDE see the file CHANGES.txt

For details about the following changes, check our JIRA install at
https://issues.apache.org/jira/browse/ivyde

List of changes since IvyDE 2.0.0-final:

- NEW: Inclusion of Ivy related schemas into the Eclipse XML Catalog (IVYDE-190) (thanks to Miguel Griffa)
- NEW: Add "Resolve Dependencies" extension to Java Project in the Package Explorer (IVYDE-153) (thanks to Jon Schneider and Troy Gaines)
- NEW: Add option to not launch a resolve after saving a file with the IvyEditor (IVYDE-197) (thanks to Jon Schneider)
- NEW: File resource listener on Ivy files launches resolve when it detects modifications (IVYDE-199) (thanks to Jon Schneider)
- NEW: Add an option in the container to automatically launch a resolve before each launch (IVYDE-204)
- NEW: "Reverse Dependency Explorer" View for synchronizing revisions across multiple projects in a workspace (IVYDE-195) (thanks to Jon Schneider)
- NEW: Make the Ivy console filter on the logging level (IVYDE-205)
- NEW: Support for Eclipse variables (IVYDE-152)

- IMPROVE: Wrap cache cleaning in a job so that it does not block the workspace (IVYDE-207) (thanks to Jon Schneider)
- IMPROVE: Allow workspace resolver to skip version matcher (IVYDE-187) (thanks to Phillip Webb)
- IMPROVE: Filter closed projects from workspace selection dialog (IVYDE-249) (thanks to Sebastien Moran)

- FIX: "Ivy Settings Path" Browse button results in an incorrectly formatted URL (IVYDE-191) (thanks to Jon Schneider)
- FIX: Workspace Resolver Prevents Source Download (IVYDE-188) (thanks to Phillip Webb)
- FIX: Resolve in Workspace fails to find projects under certain conditions (IVYDE-186) (thanks to Adam Karl)
- FIX: The gui wizard crash when adding a IvyDE Managed Dependencies library to a .launch file's classpath (IVYDE-200)
- FIX: Ivy Library removed from the list of Java EE Module Dependencies after changing its properties (IVYDE-178)
- FIX: Ivy Classpath Contributed to Dependent Projects When not Exported (IVYDE-193)
- FIX: Incorrect project:// path in the ivysettings configuration make the UI crash (IVYDE-203)
- FIX: conf attributes must not be null (IVYDE-209) (thanks to Ivica Loncar)
- FIX: Errors are not reported when multiple resolve are launched (IVYDE-219)
- FIX: Ivy settings file cannot be loaded via http url (IVYDE-218)
- FIX: The workspace resolver doesn't resolve conflicts correctly (IVYDE-212)
- FIX: dependency order not preserved causing failed builds (IVYDE-170)
- FIX: Can not add a project specific property file when adding a library (IVYDE-228)
- FIX: IvyDE fail on project close to trigger resolve on dependent project (IVYDE-229)
License
Compatibility

Upgrading/Downgrading

This version is compatible with every earlier Apache release (since 2.0.0.alpha1). Any upgrade of IvyDE should work without any worries.

The reverse is not true, downgrading is not supported and may break your configuration

Dependency on Ivy

IvyDE expects to be used with a version 2.1 or superior of Ivy.

Eclipse integration

IvyDE has been maintained to be compatible with Eclipse 3.2, 3.3, 3.4 and 3.5.

JVM compability

IvyDE has been kept compatible with Java 1.4.

Installation

Install the last release via Internet

For most user who have access to the internet it is simpler to install the latest release from the IvyDE updatesite. So just look out there:
http://ant.apache.org/ivy/ivyde/download.cgi

Manual install

Install IvyDE

So you should have the zip distribution of IvyDE in which you should find these files: You can then install them by copying them respectively in the $ECLIPSE_HOME/features and the $ECLIPSE_HOME/plugins: 
cp features/* $ECLIPSE_HOME/features
cp plugins/* $ECLIPSE_HOME/plugins

Install the latest Ivy bundle

Get the latest Ivy feature and bundle for the updatesite: And then just copy them respectively in the $ECLIPSE_HOME/features and the $ECLIPSE_HOME/plugins folders.

Restart Eclipse

After installing manually your plugins, you have to restart your Eclipse to have it take into account the changes. It is recommended to restart it with the -clean option on the command line.

Classpath Container

The IvyDE classpath container will help you manage the classpath of your Eclipse projects, based on the dependencies declared in Ivy files found in your projects.

Some of the tasks that can be performed on the container include:
Create a container

First, locate an ivy.xml file or a maven pom.xml ready to be used to build a classpath. Also, if necessary, locate a supporting ivysettings.xml.

Fast creation

For most of the projects, the ivy.xml file (or the pom.xml) is in the java project. So you can just right click on the ivy.xml and select "Add Ivy Library..." and you can directly access the prefilled setup of the IvyDE classpath container

Standard creation

The standard way to add the IvyDE classpath container is to manipulate the Eclipse's "Build Path":
  • You then might want to use specific settings for your project, a configuration different from the global one. Click on the "Enable project specific settings" check box. For additional configuration options, see the documentation about Eclipse variables.

    • Now your classpath is set and you can see all dependencies in one unique folder of the package explorer (folder name = ivy-file-name[conf1,conf2]).


    Edit the classpath

    During the life of your project, you can change the ivy.xml file or maven pom.xml and change its configuration.

    These properties can be accessed by he context menu of the IvyDE classpath container:

    You can also edit it via the build path configuration. Open the build path configuration dialog, select the "Libraries" panel and select the IvyDE classpath container. Then click on the "Edit" button: the IvyDE classpath container configuration dialog will pop up.
    This is particularly useful when Eclipse hides the empty classpath containers (since Eclipse 3.3). When the container is empty, this is the only way to trigger a resolve on this project.



    Launching resolve

    You can explicitly ask for Ivy dependency resolution from your classpath container.

    This command will invoke the "resolve" ivy task and update your classpath container.

    There is also a "refresh" action: this action is similar to the resolve one, but does not perform a full resolve if a report already exists in the cache. This is particularly useful if you work with Ant and a command line so that you avoid two full resolves. It is also the default action performed on classpath containers when the Eclipse workspace is opened (Windows > Preferences > Ivy), in effect restoring the classpath container to its state prior to the last closing of the workspace if no other action is performed against the ivy.xml in the meantime.


    You can also trigger a resolve (not a refresh!) of every IvyDE classpath container in the workspace via the button in the tool bar of Eclipse.


    And to launch a resolve on a specified selection of projects:

    Retrieve dependencies

    It is possible to make IvyDE copy resolved dependencies into your project: a retrieve of the dependencies can be triggered on each resolve of the classpath container.

    To enable this behavior, enter the classpath container configuration panel, and select the second tab, "Retrieve".

    The Retrieve pattern specifies the location where the dependencies should be copied relative to the containing project.

    The Delete old retrieved artifacts check box will cause IvyDE to clean the output directory before each retrieve. Note that any other artifacts other than those previously retrieved by IvyDE in this container will be deleted as well if this option is selected.

    Finally, you can select which Configurations should be resolved and you can select which Types of artifacts should actually be retrieved. In both fields, * means all.

    Clean the caches

    IvyDE has the ability to clean the various types of Ivy caches.

    On a configured IvyDE classpath container, open the context menu and select the Clean Ivy cache entry. A menu of configured caches will be shown.
    Reload settings

    In case you have selected the "Reload the settings only on demand" option in the preferences, you can manually reload the settings via the context menu on the classpath container.

    Notes:
    Resolve in workspace

    Some projects are composed of mulpliple modules. Often, these modules have dependencies between them, dependencies managed by Ivy (of course!).

    Eclipse is capable of calculating the workspace's build order according to dependencies between projects. To leverage this advantage, IvyDE has the ability to add a project reference to a dependency located in the workspace in place of downloading its published artifact(s) from the repository. In this way, developers can develop multi-module applications, and test the interaction between these modules, before building and publishing artifacts to the repository.

    Consider a multi-module application with a considerable amount of code in each of several projects. Many developers have experienced the delays involved in waiting for Eclipse to build code across all of these projects even though development is only being conducted in one isolated part of the application (maybe just one or two projects). If the latest published artifact in the Ivy repository has the same source code as a module that the developer is not currently working on, simply closing that project in the Eclipse workspace and resolving dependencies on dependent projects that would resolve that artifact speeds the compilation process considerably.

    First, each application module should be separate a project in Eclipse, and each of these projects should have a configured IvyDE classpath container.

    To enable resolution in the workspace, go to the advanced configuration panel of the classpath container and select Resolve dependencies in workspace.

    Important notes: to make the resolve in workspace work correctly the info in the ivy.xml should be properly set: Having two projects "A" and "B" configured to use IvyDE and the workspace resolver, here is the expected resolved dependencies:
    A dependency on BB declared revisionresult
    latest.integration1.2B wired on A
    1.21.2B wired on A
    [1.2,1.3)1.2B wired on A
    1.01.2no project wiring
    latest.integrationnoneB wired on A
    1.2noneB wired on A
    [1.2,1.3)noneB wired on A
    latest.integration$versionno project wiring
    1.2$versionno project wiring
    [1.2,1.3)$versionno project wiring
    Launch configuration

    The IvyDE classpath container can also be used in the launch configuration, run or debug.

    Default behavior

    By default, the container will be used because it is included in the default classpath of you project. This is the configuration that you implicitly have when you do a "Run As..." on a Java class. The container you see in the launch classpath is the same as the one you have in your project in the package explorer.

    Launching with the default the compile classpath might not be appropriate for some situations. For example, you may have additional libraries included in the container under a configuration intended to support unit testing but that may cause some instability in the runtime application.

    Managing the classpath manually

    When you do need to have finer-grained control over which configurations are visible to the runtime classpath, it is possible to edit the runtime classpath manually.

    By creating a launch configuration, you will get the default classpath as described above. So the first step is to remove it. Most likely, you will want to re-add your project in the user entries. Then to add an IvyDE container, choose "Advanced":

    Choose "Add Library":

    Choose "IvyDE Managed dependencies":

    Select the absolute path to your ivy.xml and select the proper configurations:

    Note: in the launch configuration it is not possible to edit or launch a resolve manually on the container you are creating. But it is possible to launch a resolve before each launch. It is recommended to do so if the resolve process is not too long. Otherwise you will have to recreate the container each time you change something in the ivy.xml for instance.

    To enable the resolve before each launch, go into the "Advanced" tab and select "Resolve before launch".

    Click "Finish" and see the result:

    Use with maven poms

    If you want to use a maven pom.xml instead of an ivy.xml file, you can select a pom file in the configuration options of the IvyDE classpath.

    When a maven pom is selected, the configurations list is updated with all maven scopes.

    Both examples below are a good illustration of the simplicity of using maven poms in IvyDE:

    Maven1 Sample

    This sample presents a simple use case involving a maven pom and the IvyDE classpath container. We are going to create an Eclipse project on commons-httpclient sources.

    - Download the commons httpclient sources

    - Unzip this file (c:/tmp/commons-httpclient/)

    - Create a new Eclipse java project based on the unzipped sources (c:/tmp/commons-httpclient/)


    Note: your project willnot compile: some imports cannot be resolved.
    - Add a new classpath container based on the "project.xml" pom and select "default" configuration (maven scope)

    - Finished. The project compiles!

    Maven2 Sample

    This sample demonstrates how the IvyDE classpath container on a Maven2 pom can handle transitive dependencies.

    - Create a new empty java project in Eclipse.

    - In your project, create an ivysettings.xml file: 
    <ivysettings>
    	<conf defaultResolver="ibiblio"/>
    	<resolvers>
    		<ibiblio name="ibiblio" />
    	</resolvers>
    </ivysettings>
    Using the m2compatible attribute, you can benefit from Maven2 repository compatibility.

    - In your project, create a pom.xml file: 
    <project>
    	<modelVersion>4.0.0</modelVersion>
    	<groupId>com.mycompany</groupId>
    	<artifactId>myproject</artifactId>
    	<version>1.0-SNAPSHOT</version>
    	<dependencies>
    		<dependency>
    			<groupId>commons-httpclient</groupId>
    			<artifactId>commons-httpclient</artifactId>
    			<version>3.0</version>
    		</dependency>
    	</dependencies>
    </project>
    - On the pom.xml file, open the context menu and click on "Add Ivy Library...":

    - Select the configurations compile and runtime

    - Go into the "Settings" tab, select "Enable project specific settings" and click on the "Workspace..." button

    - Choose the ivysettings.xml file in your project

    - click "Finish"

    - That's all! Your IvyDE classpath container resolves all dependencies including those that were transitive to the commons-httpclient module!

    WTP integration

    WTP refers to the Web Tools Platform project from the Eclipse foundation which allows Eclipse users to easily develop, launch and debug web applications. IvyDE works with WTP 2.0+ (Eclipse 3.3+).

    In the properties of your project configured to use WTP, there is a section titled "Java EE Module Dependencies". In this section you will find the IvyDE classpath container listed, usually with the name "ivy.xml [*]". Select it and dependencies found in the IvyDE classpath container will be deployed as well.

    This has been successfully tested with Eclipse 3.3/WTP 2.0, and Eclipse 3.4/WTP 3.0.

    IBM Rational Application Developer (RAD) 7.5.3+

    Users of RAD 7.5.3 will notice that the classpath container is not listed in the table. RAD prevents the deployment of classpath containers by default. To allow this behavior, selection Windows > Preferences > Java EE. Check "Allow loose classpath module dependencies". RAD will present you with a warning message. To enable the behavior, you need to check the option again in the popup and click Yes.


    Note: due to a bug in RAD 7.5.3, this IBM specific property is not persisted when we close the workbench and reopen it. To work around this:
    • Export RSA preferences ( File > Export > General > Preferences)
    • Open the exported .epf file and replace
      /instance/org.eclipse.jst.j2ee/org.eclipse.jst.j2ee.preferences.allowClasspathDep=false
      with
      /instance/org.eclipse.jst.j2ee/org.eclipse.jst.j2ee.preferences.allowClasspathDep=true
    • Load the modified .epf
    Ivy file editor

    IvyDE comes with an Ivy file editor that provides an editor that performs code completion for Ivy xml tags based on the real-time state of your repository. It also packs with an Ivy file creation wizard and HTML preview.

    Creation Wizard

    To use the creation wizard, choose File > New > Other > IvyDE > Ivy file in the Eclipse menu (Ctrl+N by default). Select it and click Next.

    The wizard contains only one page, and is very simple.

      Wizard fields:
    1. Container: you must select a target project. (This is already set if you access the wizard through the context menu on your project root folder).
    2. File name: the Ivy file name (ivy.xml by default).
    3. Organisation: the component owner name. (your company name or the company that provides the component if you are writing an ivy.xml file for 3rd party jars). Note that this value can be set in the Ivy preference page.
    4. Module name: the component name.
    5. Status: the status of the project. (integration by default since we have just created its ivy file. Please refer to the Ivy documentation for more details).

    Ivy Editor

    IvyDE's Eclipse editor provides XML syntax coloration, tag completion, tag attribute name completion, and dependency and configuration tag value completion.

    Completion comes with contextual help. The completion popup is displayed when through the CTRL + SPACE shortcut.

    Available completions:
    • XML structure: Allows you quickly to insert valid tags at the right place. If the tag can have nested children, both notations, simple tag and open tag, are proposed.

    • Tag attributes: When your cursor is placed in a tag bracket, the completion shows available attributes for the enclosing tag.

    • Attributes values: When your cursor is placed inside the quotes of an attribute value, the completion shows available values for the matching attribute.

        Available value completion
      • info: organisation (preference based), module (Eclipse project name),
      • info/ivyauthor: name (preference based), url (pref based)
      • info/description: homepage (pref based)
      • info/license: name
      • info/repository: name (the other attributes depend on it), url, ivys, pattern, artifacts
      • configurations/conf: visibility, deprecated, extends
      • publications/artifact: type, conf, ext
      • dependencies/dependency: org, name, rev are resolved thanks to Ivy using the ivyconf set in the project Ivy preference page. If not set to "default" Ivy uses its defaults resolvers configuration (ie Ivyrep + ibiblio), and if these are not set Ivy uses the ivyconf set in the Eclipse Ivy preference page. conf values are computed from the current ivy.xml file and the dependency ivy.xml file if any.

    Ivy settings editor

    IvyDE provides an editor of ivysettings.xml files. It provides completion on all tag and attribute names.

    Completion comes with contextual help. The completion popup is displayed through the CTRL + SPACE shortcut.

    Available completions:
    • XML structure: Allows you to quickly to insert valid tags in the right place. If the tag can have nested childrenm, both notations, simple tag and open tag, are proposed.

    • Tag attributes: When your cursor is placed inside a tag bracket, the completion shows available attributes for the enclosing tag.

    Eclipse global preferences

    IvyDE maintains a global configuration, which controls the behaviour of every Ivy instance in every project in the workspace. This global configuration can be overrided in each project.

    The global configuration can be found in the preferences of Eclipse (menu Window > Preferences for Windows and Linux users, Eclipse > Preferences for mac users), and select the item Ivy.

    Global Ivy preferences

    • On Eclipse startup: Specifies what IvyDE should do in every project containing an IvyDE managed classpath container when Eclipse is starting up.
    • On Ivy file change: Controls whether a resolve is performed each time Eclipse detects a change on an ivy.xml file configured by an IvyDE container via a save in the editor, a refresh, or a team/update.
    • Organisation: Your company name for Ivy editor completion.
    • Organisation URL: Your company web site url for Ivy editor completion.

    Classpath configuration

    • Resolve dependencies in workpace: IvyDE allows Ivy dependencies between projects in the workspace to be realized through project references rather than jars from the repository. See the documentation for further information on this feature.
    • Resolve before launch: an IvyDE container can be used in the classpath of a launch configuration, and the container can be resolved on each launch. See the documentation about launch configurations for further information on this feature.
    • Order of the classpath entries: By default, the classpath container entries are ordered by order of declaration in the ivy.xml. When there are many entries, it can be useful to have them ordered lexically for enhanced readability.
    • Accepted types: A comma separated list of extensions which will make IvyDE add the artifact to the classpath
    • Sources types: A comma separated list of Ivy "type" names which should be considered sources.
    • Sources suffixes: a comma separated list of suffixes which will make IvyDE attach as source the artifact with the suffix to the artifact without the suffix. For instance, "commons-lang-sources.jar" will be attached as source to "commons-lang.jar" with the default value.
    • Javadoc types: same as sources types but for javadocs
    • Javadoc suffixes: same as sources suffixes but for javadocs

    Retrieve setup

      If checked, a retrieve job will be triggered after each the resolve.
    • Retrieve pattern: The pattern to use for the retrieve. Check Ivy documentation for pattern explanation.
    • Delete old retrieve artifacts: On each retrieve, the previously retrieved libraries will be removed (similar to the sync argument in the Ant task).
    • Retrieve configurations: The configurations to retrieve (a comma separated list)
    • Retrieve types: The types of artifact to retrieve (a comma separated list)

    Ivy settings

    • Reload the settings only on demand: By default, IvyDE will parse the ivy settings file each times it is needed (each resolve, refresh, clean cache or completion in the ivy editor). For remote ivysettings this can slow the UI dramatically, so it is possible to make IvyDE keep the settings in a cache and only reload them via the context menu on the container).
    • Ivy settings path: The path to your ivy settings file. Leave it blank to use Ivy default resolvers. See also the documentation about Eclipse variables.
    • Property files: This is a comma separated list of Java properties files to be loaded along with the settings.

    Workspace resolver

    • Closing trigger resolve: Closing a project which has the workspace resolver enabled will trigger a resolve on every project that depends on it.
    • Opening trigger resolve: When a project is opened, IvyDE will trigger the resolve of every other project which has the workspace resolver enabled.
    • Ignore version when resolving workspace projects: This option forces the workspace resolver to ignore the version of a module specified in an ivy.xml if a project containing an Ivy file with that module organization and name is found in the workspace, instead substituting a project reference. This may have unintended consequences.
    Eclipse variables

    Eclipse contains a string substitution mecanism. This feature allows you to specify a path location that can be shared between developers.

    IvyDE uses it to find the ivysettings.xml and properties files in both the glogal preference page and the project specific preference page.

    Using the "Workspace..." button will open a window to choose a file in the workspace. IvyDE will automatically fill the field with the proper variable.

    Using the "File System..." button will allow you to choose a file in the file system. This path will not be portable.

    Finally, you can choose to depend on the Eclipse variable system by clicking on "Variable...".

    Backwards compatibility

    Previously, IvyDE supported the project://projectName/path/to/file.ext protocol. It sill does, but references of this style will be automatically converted in the saved settings to the Eclipse variable way of defining this path: ${workspace_loc:projectName/path/to/file.ext}.
    Ivy Console

    The Ivy console provides the Ivy working traces that are visible in the command console. This view can be useful for understanding what Ivy and IvyDE are doing under the covers.
    The Ivy Console can be accessed within your Eclipse Console view, by selecting the "Ivy Console" item.



    The colors in the console correspond to the different log levels. Here is the default mapping:
    • Debug: light blue
    • Verbose: green
    • Info: black
    • Warn: orange
    • Error: red
    To change the level of logging in the console, use the button in the view:


    Eclipse's Ant integration

    Most Eclipse distributions include a plugin to launch Ant build files. The provided Ant distribution is a standard distribution of Ant that doesn't include Ivy. You may wish to run Ivy targets against Eclipse's Ant distribution.

    Configure Ant classpath

    For now, IvyDE doesn't contribute to the Ant classpath of the Eclipse plugin, so you will have to do it manually.

    In the global preference page of the Ant runtime, click on Add External JARs...

    Then browse your filesystem to the plugins directory of your Eclipse installation and select the Ivy jar named org.apache.ivy_2.X.X.XXXXXXXXX.jar. Now Ivy has been added to the classpath of the Ant distribution embedded in Eclipse.

    Run Ivy targets

    Create an Ant build file and declare the Ivy targets with: 
        <taskdef resource="org/apache/ivy/ant/antlib.xml" uri="antlib:org.apache.ivy.ant" />
    And don't forgot to declare the namespace xmlns:ivy="antlib:org.apache.ivy.ant".

    After the taskdefs have been added, you will have code completion on Ivy tasks:

    The build will now be successful:

    Reverse Dependency Explorer

    Introduction

    When working with multiple projects in a workspace that represent the whole or part of a larger application, you may want to simultaneously change the revisions of dependencies in several Ivy files to a single new revision all at the same time (notwithstanding the eviction mechanism inherent to Ivy).

    At other times it is instructive just to see what dependencies are being utilized by projects in the workspace by revision without having to dig into each project and look at each individual module descriptor.

    The Reverse Dependency Explorer turns the dependency tree upside-down, exploring the workspace by organization, module, and revision and providing a mechanism to synchronize revisions across projects/classpath containers.

    Consider the following workspace, with three projects, all of which have an ivy.xml file at their project root. Each of these Ivy files has an associated IvyDE managed classpath container.


    Right clicking on any (or all) of the projects and selecting Ivy > Reverse Dependency Explorer opens the view. The explorer displays a tree structure with an item for each organization/module pair. The third column lists all of the revisions of this pair for the selected projects. Expanding a tree item, you can see the module revision that a given Ivy classpath container depends on (if at all). Note that the view only shows direct dependencies and no transitive dependencies.


    Organization/module pairs that have conflicting revisions are highlighted in red (junit in the above example). Note that in the above example, though the revisions do not match, these two revision attributes may actually resolve to the same artifact, depending on what is available in the repository. The view does not attempt to perform a resolve and match the resolved artifacts. It simply compares the text of the attributes.

    Synchronizing revisions

    To synchronize revisions, click in the column and row of the item you want to change and type in the new revision. The item should be highlighted green to indicate that it is tagged for synchronization. Click the synchronize button as shown to save your changes.


    Developer doc

    Adding new features or fixing bugs needs community involvement.
    Here you will find the basics for how to get involved:
    • How to build IvyDE from the sources
    • and the process to de a release of IvyDE
    Building

    This page describes how to build the IvyDE plugin from the source. The build is based on the Eclipse build system so it requires an Eclipse install. You also need to have an Ivy bundle installed.

    Setup of the build

    Eclipse installation

    You need first an Eclipse install which contains the PDE plugins (by default included in the "SDK" and "Classic" versions). We will refer to the eclipse installation path in the documentation as $ECLIPSE_HOME. In that $ECLIPSE_HOME folder you should have the plugins and features folders.

    It is recommended to have an eclipse installation dedicated to the build. So you will be able to have better control over the Ivy bundle installed there. And as the build clean the internal cache of Eclipse, running an eclipse and building with the same instance might raise some troubleshootings in the IDE.

    Lots of ant target depends on that Eclipse installation, so they need a baseLocation property to be defined. Note that you can avoid specifying that property in each command line by having a local.build.properties file which contains somethink like: 
    baseLocation=/home/me/tools/eclipse-3.4

    The Ivy bundle

    The IvyDE plugins depends on the Ivy 2.0 OSGi bundle. So the Ivy bundle have to be installed in the Eclipse installation before starting the build. An ant target will accomplished that task quite automatically. Inline help will be displayed when no property is specified: 
    ant install-ivy
    Note: due to an old bug in the build script of Ivy, the OSGi version of Ivy is "0.0.0" for every version older than the 2.0.0-RC1. So older version than 2.0.0-RC1 is not supported.

    Building

    First somehow you got some sources, for instance from the ASF subversion repository: 
    svn co https://svn.apache.org/repos/asf/ant/ivy/ivyde/trunk ivyde-trunk
    or get directly the released sources from the distribution.

    And go into the root folder of the sources. In that folder you should see the builder, org.apache.ivyde.eclipse and org.apache.ivyde.feature folders.

    And run the build: 
    ant build -DbaseLocation=$ECLIPSE_HOME
    Then in the created directory "work" you will find a directory (something like 2.0.0.alpha1-200804171513) in which you will find the zip archive ready to be unzipped in an Eclipse install.

    Install

    After a successful build you should have a zip file at dist/org.apache.ivyde.feature-$VERSION.zip. The zip file contains the "plugins" and "features" folders ready to be unzipped in an Eclipse install. So here is the process: 
    cd $ECLIPSE_HOME
    unzip ...../dist/org.apache.ivyde.feature-$VERSION.zip
    Then start your Eclipse and enjoy !
    Releasing

    This documentation is defining every steps that needs to be accomplished when releasing IvyDE.
    In this doc, the released version is denoted as $VERSION, so it HAVE to be replaced in the command line argument accordingly. There is also some $LOGIN which is referencing your login on the Apache machines.

    Prepare

    Jira

    First in Jira make sure that no more issues are opened for the target release.

    Release branch

    Some modifications of the branch are need to do the release. So a new branch is needed: 
    svn copy https://svn.apache.org/repos/asf/ant/ivy/ivyde/trunk \
               https://svn.apache.org/repos/asf/ant/ivy/ivyde/branches/$VERSION \
          -m "Creating a release branch for IvyDE $VERSION"
    and then checkout it: 
    svn co https://svn.apache.org/repos/asf/ant/ivy/ivyde/branches/$VERSION ivyde-$VERSION

    Documentation release

    The documentation have to specify the correct version number:
    In the files:
    • doc/template.html
    The header should look like this 
    <title>${title} | IvyDE $VERSION Documentation</title>

    Release notes

    Go edit the RELEASE_NOTES.txt files. There are two things to change, marked by some TODO WHEN RELEASING:
    • the list of contributors should be filled according to the "thanks to" in the CHANGE.txt file
    • the list of bug/features fixed in the release should be filled from the one in the CHANGE.txt file
    Edit the IvyDE doc and add a new page just under the root of the documentation tree:
    • Child page title: Release Notes
    • Child page path: release-notes
    As content in that doc, copy paste the content of the RELEASE_NOTES.txt file.
    Then you should improve the style of the page by adding some h1, h2, remove unwanted line break. Normally you shouldn't care about the http link or the jira issue, xooki will take care of them.

    Commit your change

    Don't forget to commit the changes you've done into the release branch.

    Building

    Make sure you have a proper working copy with a svn status. You should have no modification.

    Then launch the build: 
    ant /release clean dist -DbaseLocation=/home/me/...../eclipse/
    And sign the artifacts: 
    ./signArtifacts.sh
    Then it is time to tag the release as soon as you are happy with your artifacts:
    svn copy https://svn.apache.org/repos/asf/ant/ivy/ivyde/branches/$VERSION \
               https://svn.apache.org/repos/asf/ant/ivy/ivyde/tags/$VERSION \
          -m "Tag IvyDE release $VERSION"
    And don't forget to set the svn:external on doc/xooki to a fixed revision. Edit the svn:external property on the folder doc/xooki in the tag and set it to the revision of the commit of the tag. It should look like: 
    xooki -r790212 https://svn.apache.org/repos/asf/ant/ivy/site/xooki/
    And commit that modification.

    Prepare the updatesite

    The instructions to build the updatesite are there:
    http://ant.apache.org/ivy/history/trunk/dev/updatesite.html

    Vote for the released artifacts

    It is recommended to publish the distribution artifacts and the updatesite in your public_html on people.apache.org directory so not only committers can test it.

    On people.apache.org, create your "staging" directory: 
    mkdir ~/public_html/ivyde-$VERSION/
    And then the copy: 
    scp dist/* $LOGIN@people.apache.org:/home/$LOGIN/public_html/ivyde-$VERSION/
    It is recommended to also deploy a staging updatesite there. See that page to know how to proceed.

    And launch the vote on the ant-dev mailing list: 
    Subject: [VOTE] IvyDE $VERSION Release

    I have built a release candidate for IvyDE $VERSION

    You can download the distribution from this URL: http://people.apache.org/~$LOGIN/ivyde-$VERSION/

    And a staging update site has been setup there: http://people.apache.org/~$LOGIN/staging/updatesite

    Do you vote for the release of these binaries?

    [ ] Yes
    [ ] No

    Regards,

    $ME, IvyDE $VERSION release manager
    Note: this page is defining when and how a release can be accepted.

    Deployment

    Publish the artifacts

    The binaries have to be pushed with their signatures and checksums in the apache dist directory. On people.apache.org: 
    cp -R ~/public_html/ivyde-$VERSION /www/www.apache.org/dist/ant/ivyde/$VERSION

    Deploy the updatesite

    Follow the instructions of that page: http://ant.apache.org/ivy/history/latest-milestone/dev/updatesite.html#deployment

    Update the documentation

    Update the table of content

    The table of content needs to be updated so that the last documentation point to that new release.

    First we need to update the external links. In svn/site/ivyde/history: 
    svn pe svn:externals .
    And: Then we need to edit svn/site/ivyde/toc.json: Then svn update your working copy (to retrieve the new history branch).

    Update the download page

    In the page svn/site/ivyde/download.html change every reference of the old version to the new one.

    Update the build script

    In the build script which generate the website (svn/site/build.xml), add the fix for the history import of the new release.
    In the target init-imported-history-ivyde, add a line with: 
    <init-imported-version basepath="ivyde" version="$VERSION" />

    Deploy

    All site editing being done, commit your changes.

    And now let's generate the site and deploy it:
    1. generate the part of the site for the new version:
      2. ant generate-history-ivyde -Dhistory.version=$VERSION
      WARNING: that target is modifiying the toc.json in the imported branch so that the generated html have a proper version declared in the toc. You should not commit that change. Once the site has been generated, you may want to revert the changes so you won't commit it by mistake. (TODO: process to improve so we shouldn't worry).
    2. generate the website with the new toc:
      3. ant /all generate-site-ivyde
    3. you should verify that the site generated in target is OK. And once your happy with it, commit the changes in target (some svn add might be needed !)
    4. deploy the website: go on people.apache.org and svn up /www/ant.apache.org/ivy/ivyde

    Post release tasks

    Jira

    Update the IvyDE Jira project: mark the version as released.

    Bump the version

    Update the versions needs to be updated in the following files:
    • build.properties (edit the qualifier)
    • org.apache.ivyde.eclipse/META-INF/MANIFEST.MF
    • org.apache.ivyde.feature/feature.xml