freemarker.org projects use a somewhat eccentric Ivy setup; the projects don't rely directly on the remote Ivy and Maven repositories, instead they maintain a mini mirror repository in the project directory (.ivy subdirectory). That fills the same role as corporate "mirror" repos: it shields you from Internet and Web-repository outages and slowdowns.
After you checked out the project, the first Ant task that you run should automatically build the mentioned mirror repository (Ivy 2.0.0 or later compatible Ant tasks must be already installed). After that, this mirror will never be update automatically; to update it, call the "update-deps" Ant task. You also have to call this task if you have added new dependencies to the ivy.xml, otherwise they will be missing from the mirror repo.
The "update-deps" task pulls the dependencies from Ibiblio (and from some other public repositories), and from http://freemarker.org/repos/ivy
. The last is our own public Ivy repository. It's used only for the snapshot versions of freemarker.org projects (the releases are on Ibiblio), and for hosting non-freemarker.org dependencies that are missing or not well maintained in other public repositories.
The snapshot versions are published in our public repo automatically after SVN commits (with a few minutes of delay), assuming the project was built successfully with your SVN commitment. To check that, visit the Continuous Integration service's homepage, http://freemarker.org/builds/.
Note: If for some reason you need to publish manually, run ant artifacts server-publish-last-build, and you will find the resulting Ivy repository file structure under build/dummy-server-ivy-repo. Upload these files with SCP or SFTP to the repository. (When using SFTP, you have to use binary mode for the XML files, or else the checksums will not match.)
Let's say you develop FreeMarker in the SVN trunk head (i.e. a snapshot version). You made some changes, but before committing you want to try how the changes affect Docgen (another project on freemarker.org, depends on the latest snapshot version of FreeMarker). To try that, you had to SVN commit, wait for the new revision be automatically published, then go into the Docgen project directory (let's assume it's already checked out), issue ant update-deps there, and only then you could try what you wanted. Not only it's slow, but if it turns out that you made a mistake in FreeMarker, it's a bit too late to realize that, as it's already committed.
The solution for the above is, instead of committing FreeMarker, you issue ant publish-override in the FreeMarker project, and then rebuild Docgen ("update-deps" is not needed at all). What does "publish-override" do? It locally (i.e., on your computer only) overrides whatever is in the mirror repos of the projects. To undo this, just issue ant unpublish-override in the FreeMarker project. This "publish-override"/"unpublish-override" thing works in all freemarker.org projects. If you lost track of what is overidden and what is not, just issue ant unpublish-override-all, in whichever project.
The Ivy setup described here is tested to be compatible with the following IDE-s:
- IntelliJ IDEA 8.1 with IvyIDEA 0.9 beta 1 (0.8 is not enough!)
In both IDE-s you have to ask "resolve" to bind the dependencies to the IDE's classpath. Remember, "resolve" will use the mirror repository, not the ones on the Internet. Thus, before resolving, the mirror repo possibly should be created/updated with the update-deps Ant task. In both above setups, the Ant runner doesn't know the Ivy Ant tasks out-of-the-box, so you have to install Ivy 2.0.0 (or later compatible) into the Ant integrated into the IDE, or else update-deps will fail.
Don't forget to configure the plugin to use the ivysettings.xml included with the project, not the default settings of Ivy. Also, you should chose the "IDE" Ivy configuration.
