Simple self-hosting is adequate for most standalone situations and is particularly well-suited to developing against the large products as targets. However, there are scenarios in which a more advanced solution is needed:
Since external plug-ins are not in the workspace, they are not part of the search scope. Therefore, various searches (for interface and class references, implementations etc.) return less results than expected. Only external libraries that are part of workspace plug-ins' class path are visible to Java plug-in.
Closely connected to 1), browsing source code of external plug-ins is only possible for plug-ins that are required by workspace plug-ins. Other plug-ins are not visible.
Class path is not stable. If you work on a number of interdependent plug-in in the workspace, PDE will express these dependencies as project references. In contrast, dependencies on external plug-ins will be expressed using ECLIPSE_HOME variable and external JARs. If these projects are shared using the repository, other developers will be forced to replicate this complement even though they do not necessarily need all the plug-ins you had in the workspace.
The obvious conclusion is that if all the plug-ins were in the workspace, these shortcomings would all be addressed. Search would work as expected, source code would be visible for all the classes and class path would be uniform i.e. would contain only project references. However, always adding the entire product from a shared repository in source form is prohibitively slow both for downloading and compilation. For this reason, a notion of binary projects is introduced.
Binary projects are regular plug-in projects that do not contain source code. As such, they are bypassed during compilation and are only used to address the shortcomings listed above. External plug-ins are brought into the workspace using the PDE import wizard.
Before importing binary projects, it is important to configure PDE for binary self-hosting. Since we will not use external plug-ins to resolved references, we should disable them in Preferences. After that, Import wizard is invoked using File->Import...->External Plug-ins and Fragments.
Most of the time, you will accept default values in the first page. By default, you are importing external plug-ins of the target run-time workbench as set in the Preferences. The first page of the import wizard allows you to change the location of the run-time workbench by providing a shortcut to the Plug-in Development->Target Platform page through the Change... button.
Importing binary projects can cause your workspace to be large in size, and the import operation itself can be time-consuming depending on the number and content of the plug-ins being imported. To get around these problems, PDE has introduced the notion of importing with linking. If you uncheck the 'Copy plug-in contents into the workspace location' checkbox, PDE will not import the contents of the plug-ins you selected into the workspace. What it will do instead is create projects for these plug-ins in your workspace, and create a linked resource for every file that was to be imported. These linked resources point to the actual files in the install and will show up in your workspace as if they were explicitly imported. You will able to browse them, but you won't be able to modify them, as modifying these files will result in the modification of the original files. Deleting a binary project will of course delete all the linked files contained in it.
Automatically attaching source code to a JAR file and the extracting source archives option require PDE to find the zip file containing the source. PDE has two requirements for this task:
1. The zip file must be named properly. f the library name is xyz.jar, the zip file containing source for that library must be named xyzsrc.jar.
2. The zip file must either be alongside the JAR file or in one the declared source code locations. In Eclipse, source code is packaged in separate plug-ins, and source code locations are declared using the 'org.eclipse.pde.core.source' extension point. PDE automatically goes through all the extensions in your target platform, computes all the source code locations found in that platform, and adds them to the Plug-in Development->Source Code Locations preference page.
If you import from a location other than the target platform as specified on the Plug-in Development->Target Platform page, and your source code is packaged using the 'org.eclipse.pde.core.source' extension points, make sure to add those source code locations manually to the Plug-in Development->Source Code Locations page, so that PDE can successfully locate the source.
Library paths sometimes contain variables, e.g $ws$. PDE substitutes values set on the Plug-in Development->Target Environment page to substitute these variables. If these values are incompatible with the platform you're importing from, the first page of the import wizard provides a shortcut to that preference page through the Change... button which allows you to modify values on that preference page.
When Next is pressed, the wizard will compute all import candidates and make them available in a list of checkboxes. The actual set of plug-ins you will select depends on the way you self-host.
If you are working on plug-ins that are not already present in the target platform, you will want to select all the choices (Select All). If some of the plug-ins on the list are already in the workspace in source form, you will want press Existing Projects, then Invert Selection. This will result in selecting all the plug-ins that are not in the workspace already.
When you press Finish, selected plug-ins will be imported into the workspace. PDE will also set their class path and associate source archives with libraries so that you can browse or debug them.
When there is a large number of binary projects in the workspace, it is hard to tell them apart from source projects. PDE provides two complementing ways to handle this problem. It provides for label decorator that adds a 'binary' icon overlay to the regular project icon to clearly mark the binary project. You can turn it on in Preferences under 'Workbench->Label Decorations'. In addition, PDE contributes binary project filter to Java Explorer view. When engaged, it will hide binary projects and leave only those you are working on.