Section 26.2.  The Shape of Plug-ins

26.2. The Shape of Plug-ins On disk, a plug-in can either be a directory of files or a JAR containing files. Figure 26-1 shows the UI plug-in structured as a JAR, as you saw in Section 2.2, "Inside Plug-ins." Figure 26-1. JAR'd plug-in layout Figure 26-2, on the other hand, shows the org.eclipse.ui plug-in as a directory. Notice that everything is the same, except the code is in ui.jar rather than in the org directory. Figure 26-2. Plug-in disk layout These two forms of plug-ins are equivalentthe Eclipse Runtime and tooling (e.g., PDE, Update, etc.) manage both forms equally well. Below are some useful tips to help you decide which format is best for your plug-ins: Use directories If the plug-in contains many files that must be directly on the native filesystem. Examples of such files are shared libraries (e.g., DLLs), program executables, and JARs. Most Eclipse facilities (e.g., classloaders, Intro, Help, About, etc.) transparently extract the required files on-demand, so the main concern here is efficiency. Extracting doubles the disk footprint and incurs a one-time cost. If the plug-in has many such files or they are large, consider packaging the plug-in as a directory. Use JARs If the plug-in contains many small files that would otherwise fragment the disk. If the plug-in contains highly compressible files. If you want to sign the plug-ins and have that signature maintained after installation to support install verification and running with security (e.g., for Web Start). The Eclipse SDK is about 75% JAR'd plug-ins. Of those that are not JAR'd, more than half are documentation, source, and other plug-ins that include large volumes of nested archives. The rest are left as directories for various reasons, as mentioned above. So, in Eclipse 3.1, deploying plug-ins as JARs is the norm rather than the exception. While this is transparent to both the user and the developers coding to the API of the plug-in, there are a few considerations to note for the developers of JAR'd plug-ins: JAR'd plug-ins should always have a classpath of "." or no classpath specification (this implies "."). A "." signifies that the JAR itself is the classpath entry since the JAR directly contains the code. It is technically possible to run a JAR'd plug-in that has nested JARs on the classpath. Such nested JARs are automatically extracted and cached by the OSGi framework. As noted earlier, this effectively duplicates the amount of disk space required for the plug-in. More significantly, however, the tooling (both PDE and JDT) is unable to manage classpaths that include nested JARs. The net result is that while your plug-in runs, it takes more space and others cannot compile against it. Similarly, Eclipse understands JAR'd plug-ins with code in packages that do not start at the root of the JAR (e.g., /bin/org/eclipse/...). Again, the tooling is not set up for that structure. In particular, all standard Java compilers recognize only package structures directly at the root of a JAR. As such, developers are unable to code against JARs structured in this way. The PDE export operations automatically JAR plug-ins that have "." on the classpath and create directory structures for those that do not.