Documentation (2.0.0.final)

IvyDE is the Eclipse plugin which intergrate Ivy into your java development enviromnent. It includes: And IvyDE can be also used with other plugins like WTP or 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 integrate 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 first release considered as stable since the project as been hosted
by the Apache Software Foundation.

Major Changes in this Release

The "resolve in workspace" feature (make IvyDE search for Ivy dependencies
directly into the Eclipse projects) has been introduced in the last release
but was quite experimental. It has been refactored to be more reliable and
have been reported to be working like a charm by some of the IvyDE early users.

The IvyDE user documentation is now available directly into the Eclipse help center.

IvyDE can now load property files along with the Ivy settings.

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

Contributors
Daniel Becheanu
Eugene Goldfarb
Will Gorman
Marko Niemi

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-beta1:

- NEW: Add the IvyDE documentation to the Eclipse help (IVYDE-150)
- NEW: Export IVY_HOME as a classpath variable (IVYDE-141)
- NEW: Support variables in ivyconf.xml (IVYDE-13) (thanks to Will Gorman)
- NEW: Allow to manually reload the settings (IVYDE-26)
- NEW: Allow to not trigger full resolve at startup (IVYDE-74)

- IMPROVE: Split the global configuration panel into sevral ones (IVYDE-151)
- IMPROVE: Add ivy.xsd to ivy.xml template (IVYDE-165) (thanks to Marko Niemi)
- IMPROVE: Better support the resolve in workspace feature (IVYDE-153) (thanks to Eugene Goldfarb)

- FIX: When migrating from ivyde alpha to ivyde beta eclipse is throwing NPE at startup (IVYDE-136) (thanks to Daniel Becheanu)
- FIX: The retrieve configuration doesn't support '*' as accepted types (IVYDE-137) (thanks to Daniel Becheanu)
- FIX: NPE when a project:/// path is used and path does not exist (IVYDE-144)
- FIX: project://[projectname]/ scheme for settings only work with java projects, not simple projects (IVYDE-145)
- FIX: source and javadoc attachment regression (IVYDE-146)
- FIX: IvyDE does not save "Configurations" and "Types" field values for "Retrive" tab (IVYDE-142) (thanks to Daniel Becheanu)
- FIX: Retrieve after resolve task fails because of wrong resolve configuration (IVYDE-140) (thanks to Daniel Becheanu)
- FIX: Conversion from "file:" to "project:" fails (IVYDE-143) (thanks to Will Gorman)
- FIX: The decorators can throw a NPE at startup (IVYDE-133)
- FIX: Changing any setting for the classpath container loses the "exported" setting of the classpath container (IVYDE-149)
- FIX: IvyConsole:java.io.IOException: Output Stream is closed (IVYDE-130)
- FIX: "Delete old retrieved artifacts" gets grayed out after OK'ing the dialog (IVYDE-155)
- FIX: REGRESSION: Resolving does no longer respect configurations (IVYDE-161)
- FIX: Parsing ivy file fails in IvyDE while it succeeds in Ant (IVYDE-35)
- FIX: Sources attach but Javadocs don't (IVYDE-166)
- FIX: Branch in repository pattern and defaultBranch (IVYDE-168)
- FIX: The resolve in workspace is being evicted by transitive dependencies (IVYDE-169)
- FIX: Error messages when setting path to ivy settings file covers what is being typed in (IVYDE-172)
- FIX: ResolveAllAction does not resolve multiple IvyDE containers in a single project (IVYDE-175)
- FIX: The sources/javadocs are not added for dependencies which don't have a fixed revision (IVYDE-174)
- FIX: Refresh action is detaching javadoc and sources (IVYDE-176)
- FIX: Add Ivy Library command adds classpath container even though it already exists (IVYDE-164)
- FIX: Importing a project with Ivy configured with an embedded ivysettings fails (IVYDE-181)
- FIX: Importing a project with Ivy fails if properties files are specified in settings (IVYDE-182)
- FIX: IvyDE does not set javadoc archive path properly (IVYDE-179)

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.0 or superior of Ivy.

Eclipse integration

IvyDE has been maintained to be compatible with Eclipse 3.2 and has been successfully tested and used with Eclipse 3.3 and 3.4.

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

As the Ivy's ant target to manage classpath, the IvyDE classpath container will help you manage the classpath of your Eclipse project, based on the dependencies declared in the Ivy files.

So you probably want to:
Create a container

First you should have somewhere an ivy.xml file or a maven pom.xml ready to be used to build a classpath, along if needed with an ivysettings.xml.

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. For the ivy settings, click on the "Enable project specific settings" check box.

    • Your class path is set and you can see all dependencies in one unique folder of the package explorer (folder name = <ivy file name>[<configuration>]).


    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 will direclty access the prefilled setup of the IvyDE classpath container

    Edit the classpath


    During life of your project you can change the ivy.xml file or maven pom.xml and change the configuration you want
    to use.

    These properties can be accessed by contextual menu of the IvyDE class path 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 you will be able to click on the button "Edit": the IvyDE classpath container configuration dialog will pop up.
    This is particularly useful when Eclipse hides the empty classpath containers (since Eclipse 3.3), and then this is only way to trigger a resolve.



    Launching resolve

    You can explicitly ask for a dependencies resolution from your class path container.

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

    There is also a "refresh" action: this action is similar to the resolve one, it just doesn't do a full resolve if a report already exists in the cache. This is particularly useful if you work also with ant and a command line so you won't do two full resolve.


    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.


    Retrieve the dependencies

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

    To enable it, enter the classpath container configuration panel, and hit the second tab "Retrieve".

    So you can choose to do retrieve after resolve the dependencies.

    The Retrieve pattern specified the location where the deendencies should be copied, location raltive to the containing project.

    The Delete old retrieved artifacts check box will enable the wipe out the output directory before each retrieve.

    And finally you can select in which Configurations the dependencies should be resolved and you can select which Types of artifact should be actually retrieved. In both fields, * will means all.

    Clean the caches

    Within IvyDE it is possible to clean the different Ivy caches.

    On a configured IvyDE classpath container, open the contextual menu and select the Clean Ivy cache entry. It will then show the list of configured caches.

    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, modules having dependencies between them, dependencies managed by Ivy (of course!). Then sometimes we need to build and publish some modules before building the dependant one. Eclipse can handle classpath composed of Java project, it can handles dependencies between projects, and IvyDE can use that feature.

    First every of your modules should be separated projects in Eclipse, and each of this project should have an IvyDE classpath container configured.

    To enable resolution in the workspace, go into 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:
    Use with maven poms

    If you want to use a maven pom.xml instead of ivy.xml file, you just have to select a pom file in the configuration form of IvyDE class path.
    When a maven pom is selected, the configurations list is updated with all maven scopes.

    Both examples below are a good illustration of maven pom use simplicity :

    Maven1 Sample

    This sample presents a simple use case of maven pom for IvyDE class path 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/)


    Notes: your project do not compile: some imports cannot be resolved.

    - Add a new class path container based on the "project.xml" pom and select "default" configuration (maven scope)

    - That's all : your project compiles !

    Maven2 Sample

    This sample shows that IvyDE Class path container on a Maven2 pom can handle transitive dependancies.

    - 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...":
    - That's all ! Your IvyDE class path container gets all dependencies even those that were transitive to the commons-httpclient module !

    WTP integration

    WTP is the Web Tools Platform project from the Eclipse fondation which allow to easily develop, launch and debug web applications. IvyDE can be used with this framework, but only from the version 2.0 of WTP, which is supported since Eclipse 3.3.

    In the properties of your project configured to use WTP, there is a section "Java EE Module Dependencies". There should be your configured IvyDE classpath container listed, usually with the name "ivy.xml [*]". Just select it and the Ivy dependencies will be deployed as well.

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

    Ivy file editor

    Edit your ivy files easily in eclipse with the IvyDE Plugin editor.
    IvyDE brings creation wizard, html preview and completion for Ivy xml tag, attributes but also for attributes' values!
    Choose an organisation and browse thru its projects and revisions.

    Wizard

    IvyDE comes with a wizard that allows you to create an ivy.xml file for your project.
    To open the wizard choose File->New->Other in the Eclipse menu (Ctrl+N by default)
    The Ivy wizard is accessible in the category Other. Select it then click Next

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

      Wizard fields:
    1. Container: you have to select the targeted project. (This is already set if you access the wizard thanks right click menu on your project root folder)
    2. File name: the ivy file name. (ivy.xml by default and its better to keep it in most of case)
    3. Organisation: the component owner name. (your company name or the company that provides the component if you are writing ivy.xml file for 3rd party jars). Note 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 Ivy documentation for more details)
    When the form is correctly filled you can press Finish button. Eclipse will automatically open the Ivy editor.


    Ivy Editor

    The Ivy's eclipse editor provides xml syntax coloration, tag completion, tag's attribute names completion, and for dependency and configuration tag value completion.

    Completion comes with contextual help. The completion popup is displayed when hitting simultaneously the CTRL and the SPACE keys.


    Available completions:
    Ivy settings editor

    IvyDE provides an editor of ivysettings.xml files which make the edition of such files simple. It provides completion on every tags and attribute names.

    Completion comes with contextual help. The completion popup is displayed when hitting simultaneously the CTRL and the SPACE keys.

    Available completions:
    Eclipse global preferences

    IvyDE maintain a global configuration, which control the behaviour of every Ivy instance in every project in the workspace. Though this global configuration can be overided 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

    Classpath configuration

    Retrieve setup

    Ivy settings

    Workspace resolver

    Ivy Console

    The Ivy console provide you all the Ivy working traces that you were used to see in your command console. This view will be really useful to understand what Ivy and IvyDE are performing for you.
    The Ivy Console can be accessed within your eclipse Console view, selecting the "Ivy Console" item.



    The colors in the console correspond to the different log levels. Here is the default mapping:
    Eclipse's Ant interation

    Most Eclipse distribution includes a plugin to launch ant build files. The provided Ant is a standard distribution of Ant and so it doesn't include Ivy. But you probably want to use Ivy targets within the Eclipse's Ant.

    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 into the plugins directory of your Eclipse install, and select the Ivy jar named org.apache.ivy_2.X.X.XXXXXXXXX.jar. And that's it, Ivy has been added to the classpath of Ant embedded in Eclipse.

    Run Ivy targets

    Create an Ant build file and just 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".

    Then you will be able to have completion on Ivy tasks:

    And run successul build:

    Developer doc

    Adding features or fixing bugs needs a little more involvement.
    You will find here the basics to get into it:
    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: 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: Edit the IvyDE doc and add a new page just under the root of the documentation tree: 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"

    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.

    Deploy

    Commit your changes, and proceed to the full deployment of the website (regenerate every page as the toc changed: ant /all generate-site-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: