This writing describes how to setup your Eclipse development environment for freemarker.org projects (FreeMarker, Docgen, etc.).
Install the following Eclipse pulgins:
At least in IvyDE 2.0.0.beta1, Ivy is not added automatically to the Ant classpath of Eclipse. Unless that was improved since then, some manual intervention is needed: Grab ivy-x.x.x.jar from somewhere (ivy-2.0.0.jar at the time of this writing), copy it to some safe location (like if you have a standalone Ant installation, into the lib directory of it). Then in the Eclipse preferences, find Ant/Runtime/Classpath, highlight "Ant Home Entries", press "Add External Jars", and point to the ivy-x.x.x.jar.
In Eclipse open the SVN Perspective (Window/Open Perspective, etc.). In the "SVN Repositories" tab that should appear click "Add SVN repository" somewhere (or "New Repository location" or whatever it's called). For the location give: https://freemarker.svn.sourceforge.net/svnroot/freemarker
Now you can expand this newly added node to explore the tree structure of the repository. Let's say you want to fiddle with the latest development version of FreeMarker, so find trunk/freemarker, right-click on it, and select "checkout". After going through some trivial dialogs it will download the sources into your workspace. Some error dialog regarding Ivy and dependencies will pop up, just OK it for now. Switching back to the Java Perspective you should see the project... with the dependency errors (among others). In the next step we get rid of them.
Note: Currently, this part doesn't stand for FreeMarker 2.3.x (SVN: branches/2.3/freemarker). There you have to call the "fetchlibs" Ant task to download the dependencies (Ivy is not used), and after that refresh the project view (select project node, then F5).
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: shields you from Internet and Web-repository outages and slowdowns. So Eclipse tries to pull the dependencies from that mirror repository, but that's empty at the moment, hence the Ivy error. To fill it, open the Ant View of Eclipse, add the build.xml of the project, and double-click on the "update-deps" task. That will create the mirror repo. But Eclipse doesn't automatically sync itself with the repo, for that you had to right-click on the ivy.xml node in project tree that has a pile of books as its icon (not the plain XML file!) and there chose "resolve". But due to some Eclipse or plugin bugs that ivy.xml-with-a-pile-of-book node is often not shown... in that case in the Eclipse icon bar you should find a "Resolve all dependencies" icon (little yellow arrows), clicking that should fix the situation. Some errors will still remain; see them in the step 4.
Don't forget; whenever you edit the ivy.xml, or want to grab the latest version of the spanshot dependencies, you will have to run "update-deps" manually. Then, since that only updated the mirror repo, in Eclipse you will have to right-click on ivy.xml (with the book icons, not the plain XML file node!) and chose "resolve". In exchange you don't have to afraid of being offline or of public repos failing; everything, including all the Ant tasks work from your swift local repo only.
See also: Using Ivy in FreeMarker and related projects
The FreeMarker project has some generated Java source files, and after checkout they will be missing, causing errors that Eclipse signals. To fix that, go to the Ant View, and double-click on "freecc" (or if that's missing, then "javacc"). This will generate the required files. Then click on the project node, and press F5 (refresh). Now all errors should be gone.
