| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML> | |
| <HEAD> | |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> | |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> | |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> | |
| <title>Fragments</title> | |
| </head> | |
| <BODY BGCOLOR="#ffffff"> | |
| <h1>Binary project self-hosting</h1> | |
| <p CLASS="BodyText">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:</p> | |
| <ol> | |
| <li> | |
| <p CLASS="BodyText">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.</li> | |
| <li> | |
| <p CLASS="BodyText">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.</li> | |
| <li> | |
| <p CLASS="BodyText">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.</li> | |
| </ol> | |
| <p CLASS="BodyText" align="left">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 <b>binary projects</b> is introduced.</p> | |
| <p CLASS="BodyText" align="left">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.</p> | |
| <p CLASS="BodyText" align="left">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 <b>File->Import...->External | |
| Plug-ins and Fragments</b>. </p> | |
| <p CLASS="BodyText" align="center"> | |
| <img border="0" src="images/binary-import1.gif" alt="Import External Plug-ins wizard - first page" width="490" height="556"></p> | |
| <p CLASS="BodyText" align="left">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 <b>Plug-in Development->Target Platform</b> page | |
| through the <b>Change...</b> button.</p> | |
| <p CLASS="BodyText" align="left">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 | |
| <b>importing with linking</b>. 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.</p> | |
| <p CLASS="BodyText" align="left"> </p> | |
| <p CLASS="BodyText" align="left">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:</p> | |
| <p CLASS="BodyText" align="left">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.</p> | |
| <p CLASS="BodyText" align="left">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 <b>Plug-in | |
| Development->Source Code Locations</b> preference page.</p> | |
| <p CLASS="BodyText" align="left">If you import from a location <b>other than</b> | |
| the target platform as specified on the <b>Plug-in Development->Target Platform</b> | |
| page, and your source code is packaged using the 'org.eclipse.pde.core.source' | |
| extension points, make sure to add those source code locations <b>manually</b> | |
| to the <b>Plug-in Development->Source Code Locations </b>page, so that PDE can | |
| successfully locate the source.</p> | |
| <p CLASS="BodyText" align="left">Library paths sometimes contain variables, e.g | |
| $ws$. PDE substitutes values set on the <b>Plug-in Development->Target | |
| Environment</b> 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 <b> | |
| Change...</b> button which allows you to modify values on that preference page.</p> | |
| <p CLASS="BodyText" align="left">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.</p> | |
| <p CLASS="BodyText" align="center"> | |
| <img border="0" src="images/binary-import2.gif" alt="Import External Plug-ins wizard - second page" width="490" height="556"></p> | |
| <p CLASS="BodyText" align="left">If you are working on plug-ins that are not | |
| already present in the target platform, you will want to select all the choices | |
| (<b>Select All</b>). If some of the plug-ins on the list are already in the | |
| workspace in source form, you will want press <b>Existing Projects</b>, then <b>Invert | |
| Selection</b>. This will result in selecting all the plug-ins that are not in | |
| the workspace already.</p> | |
| <p CLASS="BodyText" align="left">When you press <b>Finish</b>, 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.</p> | |
| <p CLASS="BodyText" align="left">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.</p> | |
| <p CLASS="BodyText" align="center"> | |
| <img border="0" src="images/binary-projects.gif" alt="Binary projects with icon overlay in the Package Explorer" width="182" height="492"></p> | |
| <p CLASS="BodyText" align="left"> </p> | |
| <p> <br> | |
| <a href="../hglegal2003.htm"> | |
| <img src = "../images/ngibmcpy2003.gif" alt="Copyright IBM Corporation and others 2000, 2003" border="0" width="324" height="14"></a> | |
| </p> | |
| </body> | |
| </html> |