Eclipse 3.0 and previous was shipped such that each plug-in was a directory that contained code in a JAR, along with multiple other files. In order to improve the number of files that we ship along with the size of the Eclipse distributions, we would like to be able to ship each plug-in as a single JAR file containing its code and other resources. This document describes the effort getting this item to happen, and lists the issues preventing success.

• File handles - There have been reports where people have been using very large products based on Eclipse and they have run out of file handles. If all plug-ins were shipped as JAR files, then at most you would only have one file handle per JAR file (if all plug-ins were activated).
• File size - If all files are in a single JAR file and that JAR is compressed, then it will take up less space than if the plug-in was extracted to disk. Note that the gain here is only the compression of the non-code files since the code in a normal install is in a JAR anyway.
• File size on the file-system - When plug-in are installed on a file-system, they can take up more space than just the file size. Depending on the file-system and the make-up of the plug-in, the size on disk can be upwards of 20% larger.
• Install time - For Eclipse and products built on top of Eclipse, we antcipate a shorter install time based on the fact that it is quicker to install (for instance) 100MB of data in 10 files than it is to install 100MB if data in 10,000 files.
• Un-install time - Similarly it is quicker to delete a smaller number of larger files than a large number of small files.
• Mixed Mode - It is important to note that plug-ins will be able to live in a mixed JAR'd and non-JAR'd world. For instance, in the /eclipse/plugins directory there will be a mixture of JAR files and directories, both containing plug-ins.
• Signing JARs - We are looking to sign jars. Permissions can be granted on a signer basis. Install integrity can be confirmed by checking signatures.
• Simple - This approach is consistent with the Java model of jars on a classpath.

• Missing images - If you are running a JAR'd Eclipse and there are missing images, it might be the case that the plug-in developer is trying to access the images via java.io.File API rather than by calling Bundle#getEntry.

Issues [main bug 85065] [Open] [Closed]

• [bug 83469, bug 88099] Cannot run with OSGi as a JAR - Currently the conversion tool hacks the eclipse.properties file to set the osgi.frameworkClassPath key's value to be empty rather than listing the JARs in the plug-in. (which no longer exist)
• Cannot run with SWT as a JAR
• [bug 78535] Problems running from JARs.
• Performance - Need some numbers w.r.t. speed of running with JARs. What about compressed JARs?
• [bug 76653, bug 76436, bug 86561] Source code lookup
• Some plug-ins cannot be JAR'd - Note that this is ok because we can run with a mixture of both JAR'd and non-JAR'd plug-ins.
• JARs within JARs - The JAR'd plug-in format requires the class files to exist starting at the root of the JAR file. Some plug-ins have multiple JARs and its an issue to have nested JARs. Have to come up with a strategy for this.
• Modification of classpath entries in manifest files - This is added to this list not because it is a problem, but because it is work required by developers. For each plug-in, the plugin.xml or manifest.mf files need to be updated to let Eclipse know that the JARs should no longer be on the classpath and should be replaced with ".".
• [bug 86492] Icons shipped in fragments - Tod and DJ have been talking about this and are making progress. Most likely we just have to ensure our callers are using the appropriate $nl$ method calls, etc.
• [bug 85333] Plug-in holding the splash screen cannot be JAR'd - Lots of different options here, none of them good. Looks like we will add code to Main.java which temporairly extracts the splash screen and then deletes the temporary file when we are done. We would like to be able to display the splash using java code but its too hard to find SWT when you live in the startup.jar.
• [bug 91525] Plug-ins which provide intro content cannot be JAR'd
• [bug 85013] Cannot build when target is JAR'd
• [bug 87719] Problems with Ant and classloaders - Patch submitted to Platform/Ant team.
• [bug 87973] - About content cannot be JAR'd
• [bug 88254] - Test failures when running against a JAR'd Eclipse.

Goals

• Running Eclipse on JAR'd plug-ins.
• Running the test suites.
• Targeting a JAR'd Eclipse install

Milestones: Eclipse 3.1 M6 - Bundles which are part of the RCP to be shipped as JARs

• [bug 83634] Shipping Manifest files.
• [bug 87026] Running with features as JARs - Just like plug-ins will become JARs, we would like to have features as JARs as well.

Converting A Plug-in to be Shipped as a JAR

1. Change the classpath:
• If you have a manifest.mf then simply delete the Bundle-Classpath header.
• Otherwise if you have a plugin.xml then change the library entry to be a dot like this:
     <runtime>
      <library name=".">
         <export name="*"/>
      </library>
   </runtime>
• If you have additional jars (e.g., ant tasks), consult an expert.
2. Change the build.properties:
• Change all occurences of the old jar name to simply a dot. (.)
• There should be one on the bin.includes line. For instance, if your bin.includes line used to have core.jar, that will be replaced with a ..For instance: bin.includes=about.html,.,META-INF/MANIFEST.MF
• Change source.foo.jar= to source..= (that is source dot dot)
• Change output.foo.jar= to output..= (that is output dot dot)
• There may be others like jars.compile.order, etc
• If you newly generated a manifest.mf, add META-INF/ to the bin.includes.
3. Change the feature
• find all features that list your plug-in and add following to the related <plugin> tag:
      unpack="false"
4. Let Adrian know that you have JAR'd your plug-in. (for legal purposes)
5. Change about.html linked content.
• If you have content in your plug-in which is linked from your about.html file, then that content must be placed in a directory named "about_files" at the root of the plug-in.
6. Let the Release Engineering team know that you have JAR'd your plug-ins so they are able to update the javadoc generation scripts.

If you are going to switch to using bundle manifests:

• Open your plugin.xml with the PDE editor.
• On the "Overview" tab, click on the "Create an OSGi bundle manifest file" link.
• Save.
• Add META-INF/ to the bin.includes line in your build.properties (can be done in the plugin.xml editor by either checking the META-INF box on the Build page or adding the entry manually on the build.properties page.
• Determine if you still need the plugin.xml. (or fragment.xml) If the file is empty (that is, you don't have any extensions or extension points) then it can be removed. If you remove it, remember to remove the associated entries in the build.properties file too.

If you have a custom build script (build.xml):

• You need to ensure that your script will still work against plug-ins that are JAR'd as well as plug-ins which aren't JAR'd.

If you have other scripts (e.g. javadoc generation scripts):

• If the script assumes the layout of plug-ins and needs to add code JAR files to the classpath, then it must be modified to put the whole JAR'd plug-in on the classpath rather than the individual JARs.

Things to update in 3.0 manifests:

• manifest version number (Bundle-ManifestVersion: 2)
• singleton becomes a directive (singleton=true becomes singleton:=true)
• Provide-Package packages should be moved to the Export-Package header.

Conversion tool (v1.0.0) - The tool is written as an Eclipse application. It is used to JAR up an Eclipse install but the more plug-ins which are already JAR'd, the less useful this tool becomes. Our recommendation as of 3.1 M6 is to use the latest integration build to run on JAR's but if you want to JAR up everything, then try this tool. The easiest way to use it is to:

• Download tool.
• Install tool.
• Start Eclipse.
• If tool isn't part of your Target Platform, then make it so.
• Create a new Launch Configuration with the Conversion tool as the Eclipse application to run.

1. Download Eclipse.
2. Run tool to convert plug-ins to JARs. The tool basically does the following:
   1. For each plug-in...
   2. Extract all JARs to plug-in root dir
   3. Generate manifest file from plugin.xml
   4. Add "." to the classpath
   5. Zip up directory in a JAR
3. Run Eclipse.