Eclipse: Attach source/javadoc to a library via a local property

Question

I have a third-party library in my SVN repository and I'd like to associate source/javadoc with it locally in Eclipse. I.e., there should be some local setting (for example, an entry in the local.properties file) that associates the source/javadoc with the JAR file, but which doesn't introduce local dependencies into the repository via .classpath. Ideally I'd have

lib_src_dir = /my/path/to/lib/src

in local.properties and then

<classpathentry kind="lib" path="lib.jar" sourcepath="${lib_src_dir}">

in .classpath. Can this be done?

[EDIT] @VonC's answer is helpful... Is there a way to load Path Variables from a text file (e.g., local.properties) instead of going through Window -> Preferences -> General -> Workspace -> Linked Resources?

Answer 1

I believe this would be better achieved through:

• the creation of a linked folder combined with
• the declaration of a linked resource

The linked resource defines a path variable which would be equals to /my/path/to/lib/src

The linked folder would refers to your linked resource

(you can use a variable and not a fixed path, with the "Variable" button)

The variable is actually always local (to one's workspace), and will be modified through the Linked Resources preference screen.

The linked folder can also be... a linked file, thus allowing the reference of an archive through a relative path (relative to the variable).
Then this linked file (here a linked archive) can be associated to your classpathentry in the "source" attribute.

---

The problem with Linked Resources is they are local to the workspace, in the preferences.
You can export the preferences in a [myPrefs.epf] file, and then trim the exported file in order to leave only the lines containing pathvariable:

/instance/org.eclipse.core.resources/pathvariable.MY_DIRECTORY=/my/path/to/lib/src

Anyone can then import this special preference file, which will only affect the "Linked Resources" part.

That solution is not very satisfying, since the .epf preference file can not be loaded automatically in the project.
When I setup a project with a linked resources defining a path, I always leave a big README.txt at the root of my project, in order to incite the user of said project to define that same linked resources with his/her own fixed local path.

Several bugs are in progress to enhance this situation or around the Linked Resources topic.

Especially:

• Exporting a project with linked resources
• Relative paths without variables
• Have linked resources relative to workspace paths
• Would like to use path relative to workspace root

---

DevByStarlight mentions in the comments the project (not very active since Oct. 2011) workspacemechanic.

The Workspace Mechanic automates maintenance of your Eclipse environment by tweaking preferences, adding extension locations, and so on. You can use it to:

• Create a consistent environment among groups as large as the entire company, your local team, or even among your own many workspaces
• Save time setting up new workspaces
• Create tasks that ensure your favorite new preferences are applied to all your current and future workspaces. (This is one of our favorite features!)

The key to the Workspace Mechanic's behavior is the Task.
A task describes a simple test and an action that, when run, changes the environment so the test will subsequently pass.
Tasks can come in many forms: preference files, Java classes, Groovy scripts and Eclipse extensions. You can easily define your own Tasks.

It comes with a collection of scripts:

• workspace-mechanic
• workspacemechanic-settings

Answer 2

I just figured out a simple answer to this (in Indigo) after working on it in the background and free moments for a couple of days. The easiest way I've found is to expand your project in the Project Explorer, go into your Referenced Libraries, right-click the appropriate referenced JAR and click Properties. In there you have the options to designate a JavaDocs location. Enter the location of the folder that contains index.html and packages-list, files that are part of the Javadocs. Piece of cake!

The only problem I see so far is that I bet you need to do this in every projects that references that library.

Answer 3

You can do this with classpath variables.

Each developer creates a couple of new variables at Window -> Preferences -> Java -> Build Path -> Classpath Variables.

Define a variable (say, JAVA_LIB_DIR) that points to a directory containing the third-party JAR (or JARS). Define another variable that points to a directory containing the third-party source code (JAVA_SRC_DIR). You can set this up how you like, but we have a structure like this:

common/   
  lib/
    java/       <-- JAVA_LIB_DIR variable points to this directory
      axis/
      bitronix/
        1.0/bitronix.jar   "extension" is "bitronix/1.0/bitronix.jar"
      ...

In your project's build path, use the "Add Variable..." option to add the library. Then you when "attach source," you'll be prompted for a variable and extension to the source code.

This way, a single, shared .classpath file can be checked-in, while allowing each developer to locate their own library and source directories where they like.