Tuesday, October 21, 2008

Relative paths in Eclipse .link files

When setting up an Eclipse installation (or a target platform if you're doing Eclipse plug-in or RCP development), it is often recommended to use .link files to keep things organized. While this is excellent advice, all of the examples I could find use absolute paths in the .link files (for example, D:/eclipse/eclipse-plugins/MyFavoritePlugin), which is, in my opinion, less than ideal.
It turns out that the .link paths can be relative, and that is especially helpful if you want to check in your target platform into source control (CVS) or otherwise share it with others who may not install into the same absolute path (or even on the same OS).
The trick is getting the format of the path correct so that Equinox can resolve correctly. For example, here is the outline of the target platform we use for developing Skyway Builder:


In that structure, the ext/ directory contains a couple of "non-standard" features that we depend on, the RichText editor component from the EPF project, and the Maven integration plug-ins. Now here's the meat of this post, what do the .link files look like to use relative paths. The EPF-RichText.link and maven2eclipse.link files each contain one line:

Note that the paths are relative to the directory containing both the base Eclipse installation and the ext/ directory. Also note that when selecting the target platform in the Eclipse preferences, you must select /TargetPlatform/eclipse-3.3.2/ (not /TargetPlatform/).

With this structure and the .link files using these relative paths, anyone can easily check out our target platform from CVS (and store it anywhere on their local file system they want), point their development Eclipse at it, and be ready to build our source code.

If you have a target platform set up this way with relative link files, and it is a full-blown runnable Eclipse (a target platform does not need to be a full runnable Eclipse, but in my experience it usually is), you have to be careful to not ever run that target (don't launch the eclipse.exe or eclipsec.exe). Once you do, something happens that prevents it from working; for some reason the relative .link files stop working and thus it will not be a good target anymore. In our target that is checked in to CVS, we simple removed the .exe files so that nobody can accidentally run the target platform.

One final note: this should also work across platforms (the link files are not Windows or Linux or Mac specific), although I have not actually tested that. If you can try it on Linux or Mac, please let me know how it turns out.