pde-ui-home/working/site-builder.html
Parent Directory
| 
Revision Log
Revision 1.2 - (view) (download) (as text)
| 1 : | dejan | 1.1 | |
| 2 : | <h1>PDE Support for Eclipse Update Site Building</h1> | ||
| 3 : | <p>Starting from Milestone 4, PDE provides support for building update sites in | ||
| 4 : | your workspace. In this document, we will walk you through the new function by | ||
| 5 : | starting with a clean workspace and ending with a fully functioning update site | ||
| 6 : | you can browse using Update Manager.</p> | ||
| 7 : | <p><i><font color="#800000">Note: M4 driver has a small glitch that prevents | ||
| 8 : | rebuilds of the site once Update Manager uses the JARs. The fix for this problem | ||
| 9 : | dejan | 1.2 | is available in driver 20030107 and higher.</font></i></p> |
| 10 : | dejan | 1.1 | <h2>Creating the plug-in</h2> |
| 11 : | <p>We will start by creating a simple plug-in. To do so, we will use PDE | ||
| 12 : | templates to quickly create a working plug-in that has some content.</p> | ||
| 13 : | <ol> | ||
| 14 : | <li>Open 'New->Plug-in Development->Plug-in Project' wizard. Choose 'com.example.xyz' | ||
| 15 : | as the project name. Press 'Next'.</li> | ||
| 16 : | <li>Accept the default project structure. Press 'Next'.</li> | ||
| 17 : | <li>From the list of templates, choose 'Hello, World'. Press 'Next'.</li> | ||
| 18 : | <li>You can accept the defaults. Press Finish and wait for the manifest editor | ||
| 19 : | to open.</li> | ||
| 20 : | <li>Verify that the plug-in works as designed by selecting the running the | ||
| 21 : | 'Run-time Workbench' link on the first page of the dialog (just follow the | ||
| 22 : | instructions on the page). The second instance should open and it should | ||
| 23 : | have a new 'Sample Menu' and a tool bar action that opens 'Hello, World' | ||
| 24 : | message box when selected.</li> | ||
| 25 : | </ol> | ||
| 26 : | <p>Before moving on, we have to make sure that the plug-in will be built | ||
| 27 : | correctly. Content of the plug-in project is not automatically included during | ||
| 28 : | the build. The file that controls this is 'build.properties':</p> | ||
| 29 : | <ol> | ||
| 30 : | <li>Open 'build.properties' file in the project root.</li> | ||
| 31 : | <li>In the 'Build Script Variables' section on the left, press 'Add...'. | ||
| 32 : | Select 'bin.includes' from the list. Press OK.</li> | ||
| 33 : | <li>Select the newly added variable. Move to the section on the right and add | ||
| 34 : | the following by pressing 'Add' and modifying the token using editing | ||
| 35 : | in-place:<br> | ||
| 36 : | <br> | ||
| 37 : | *.jar<br> | ||
| 38 : | plugin.xml<br> | ||
| 39 : | icons/<br> | ||
| 40 : | </li> | ||
| 41 : | <li>Save and exit.</li> | ||
| 42 : | </ol> | ||
| 43 : | <p>The specification above will ensure that all the libraries, the manifest file | ||
| 44 : | and the 'icons' folder is included in the run-time version of the plug-in when | ||
| 45 : | it is built.</p> | ||
| 46 : | <h2>Creating the feature</h2> | ||
| 47 : | <p>We should now create a simple feature. Eclipse Update does not work with | ||
| 48 : | plug-ins because plug-ins are too fine-grain and usable functional chunks are | ||
| 49 : | composed of several plug-ins working together. Features are used to group these | ||
| 50 : | plug-ins, give them a name, copyright, license and other attributes important | ||
| 51 : | for deploying function.</p> | ||
| 52 : | <ol> | ||
| 53 : | <li>Open 'New->Plug-in Development->Feature Project' wizard. Choose 'com.example.xyz-feature' | ||
| 54 : | as the project name. Press 'Next'.</li> | ||
| 55 : | <li>Choose 'com.example.xyz' for feature Id, "XYZ Feature" for the | ||
| 56 : | name and "XYZ Inc." for the provider. Press Next.</li> | ||
| 57 : | <li>Choose 'com.example.xyz' plug-in from the list of plug-ins that are | ||
| 58 : | referenced by this feature.</li> | ||
| 59 : | <li>Press Finish. Wait for the feature manifest editor to open.</li> | ||
| 60 : | <li>Switch to the 'Information' page.</li> | ||
| 61 : | <li>Enter "Sample XYZ feature description" in the text area.</li> | ||
| 62 : | <li>Select 'Copyright Notice' and enter "Copyright XYZ Inc. 2003".</li> | ||
| 63 : | <li>Select "License Ageement" and enter:<br> | ||
| 64 : | <br> | ||
| 65 : | LICENSE AGREEMENT<br> | ||
| 66 : | <br> | ||
| 67 : | YOU MUST ACCEPT THIS AGREEMENT IN ORDER TO INSTALL THE FEATURE.<br> | ||
| 68 : | </li> | ||
| 69 : | <li>Save (Ctrl+S).</li> | ||
| 70 : | </ol> | ||
| 71 : | <p>Similarly to the plug-in project, features also require build.properties file | ||
| 72 : | to define what will be included in the archive during the build. By default, PDE | ||
| 73 : | wizard adds feature.xml to bin.includes variable during the initial creation. | ||
| 74 : | You need to add other files or folders you want packaged in the feature.</p> | ||
| 75 : | <h2>Creating the site</h2> | ||
| 76 : | <p>We can now create an Update Site project. Eclipse Update site is any | ||
| 77 : | directory that contains site.xml file that describes the features available on | ||
| 78 : | the site. By default, update site also contains 'features' directory containing | ||
| 79 : | the packaged feature archives and 'plugins' containing the packaged plug-ins.</p> | ||
| 80 : | <ol> | ||
| 81 : | <li>Open 'New->Plug-in Development->Update Site Project wizard. Choose | ||
| 82 : | 'Sample Update Site' for the project name. </li> | ||
| 83 : | <li>Press 'Finish'. Wait for the site map editor to open (since update site | ||
| 84 : | project does not have Java nature, the perspective will switch to 'Resource' | ||
| 85 : | in order to see it).</li> | ||
| 86 : | <li>Define a sample category. In the 'Category Definitions' section, press the | ||
| 87 : | 'Add...' button. Specify 'sample' for the name, 'Sample Category' for the | ||
| 88 : | label and "This category demonstrates how features can be | ||
| 89 : | classified." for the description. Press 'OK' and save.</li> | ||
| 90 : | <li>Switch to the Build page. Unlike other pages, this page does not define | ||
| 91 : | content of the site.xml file. Instead, it defines how features and plug-ins | ||
| 92 : | in the workspace are built in order to generate required archives. </li> | ||
| 93 : | <li>In the 'Features to Build' page, press 'Add...' button and select 'com.example.xyz' | ||
| 94 : | feature. Press 'Finish'. This will add the feature project to the list of | ||
| 95 : | features to build when 'Build Now' button is pressed.</li> | ||
| 96 : | <li>Check the feature checkbox. In addition to being built, this feature will | ||
| 97 : | appear in site.xml file and be visible to users that browse your site. Save.</li> | ||
| 98 : | <li>Switch to the 'Features' page to confirm the content. It should show one | ||
| 99 : | feature. Select it. Note how URL, Id and Version fields are defined.</li> | ||
| 100 : | <li>Focus on the 'Categories' section and check the available 'Sample | ||
| 101 : | Category' checkbox. This will classify the feature under this category. If | ||
| 102 : | not classified, the feature will appear under 'Other' category. Save.</li> | ||
| 103 : | <li>Switch back to the 'Build' page and press 'Build Now'. Wait for the build | ||
| 104 : | to finish. If everything is correct, you should have 'plugins' and | ||
| 105 : | 'features' directory under the project root and each should have | ||
| 106 : | 'com.example.xyz_1.0.0.jar' file.</li> | ||
| 107 : | </ol> | ||
| 108 : | <h2>Browsing the site</h2> | ||
| 109 : | <p>The site is now ready for browsing. We will use Update Manager to do so:</p> | ||
| 110 : | <ol> | ||
| 111 : | <li>Select 'Help->Software Updates->Update Manager'.</li> | ||
| 112 : | <li>Move to the 'Feature Updates' view. Find 'My Computer' object and drill | ||
| 113 : | down into our workspace (on the file system). You will notice that our | ||
| 114 : | Update Site project will have a different icon. Select it.</li> | ||
| 115 : | <li>Bring up the pop-up menu and choose the option "Bookmark | ||
| 116 : | Location...". For the bookmark name type "Update Site | ||
| 117 : | Preview". Press 'Finish'.</li> | ||
| 118 : | <li>Collapse the 'My Computer' node. You will notice a new bookmark object for | ||
| 119 : | our site. Expand it.</li> | ||
| 120 : | <li>You should see "Sample Category" object. Expand it.</li> | ||
| 121 : | <li>You should now see the "XYZ Feature" object. Select it. The | ||
| 122 : | content of the feature should show up in the Preview view on the right. | ||
| 123 : | Verify that Copyright, License and description is all correct.</li> | ||
| 124 : | </ol> | ||
| 125 : | <h2>Installing from the site</h2> | ||
| 126 : | <p>In order to verify that you can indeed install the XYZ Feature from the site, | ||
| 127 : | you need to use a different Eclipse instance (to avoid polluting the instance | ||
| 128 : | you are using for development). For that purpose, unzip an Eclipse driver | ||
| 129 : | somewhere else. Launch it and go directly to the Update Manager (as above - | ||
| 130 : | 'Help->Software Updates->Update Manager').</p> | ||
| 131 : | <p>Once you do, repeat the steps 1-6 defined in 'Browsing the site' (when at the | ||
| 132 : | step 2, make sure you drill down to the design instance workspace, not the test | ||
| 133 : | instance). However, this time we will go further and install the feature:</p> | ||
| 134 : | <ol> | ||
| 135 : | <li>Press the button 'Install Now' in the Preview page. The Install wizard | ||
| 136 : | will open.</li> | ||
| 137 : | <li>Accept the license agreement by selecting 'I accept...' radio button. | ||
| 138 : | Press Next.</li> | ||
| 139 : | <li>Accept the default location where the feature will be installed. Press | ||
| 140 : | Finish.</li> | ||
| 141 : | <li>We haven't digitally signed the feature, so we will receive a warning. | ||
| 142 : | Press 'Install' button to continue.</li> | ||
| 143 : | <li>The feature will now install. When finished, you will receive a message | ||
| 144 : | that a restart is needed. Press 'Yes'. Wait for the restart.</li> | ||
| 145 : | <li>Once Eclipse is up again, expand 'Current Configuration' node in the | ||
| 146 : | 'Install Configuration' view of the Update Manager perspective. Also expand | ||
| 147 : | the default install site. You should see two features: "Eclipse Project | ||
| 148 : | SDK (Windows)" and the newly installed "XYZ Feature".</li> | ||
| 149 : | <li>To confirm that the feature has been installed correctly, switch to the | ||
| 150 : | Resource perspective and reset it. You should now see the 'Hello, World' | ||
| 151 : | tool bar button and the 'Sample Menu' menu in the menu bar.</li> | ||
| 152 : | </ol> | ||
| 153 : | <h2>Advanced topics</h2> | ||
| 154 : | <h3>Publishing to a remote server</h3> | ||
| 155 : | <p>It is possible to publish the update site project to the final location on a | ||
| 156 : | remote server when using FTP/WebDav optional support (must be downloaded | ||
| 157 : | separately from the regular driver). This is a very nice feature because it | ||
| 158 : | allows you to work in the workspace, build and then upload changes to the target | ||
| 159 : | server by uploading the delta only:</p> | ||
| 160 : | <ol> | ||
| 161 : | <li>Select the update site project and bring up the pop-up menu.</li> | ||
| 162 : | <li>Choose 'Team->Target Site'. The wizard will open.</li> | ||
| 163 : | <li>Select 'FTP' protocol and press 'Next'.</li> | ||
| 164 : | <li>Select the ftp URL that includes the remote server and the path from the | ||
| 165 : | FTP root to the physical root of the site as defined by the HTTP server.</li> | ||
| 166 : | <li>Specify user name and password for the FTP account. Press Next.</li> | ||
| 167 : | <li>Specify the directory that will be the project root on the server (use the | ||
| 168 : | provided default that is the same as the project name).</li> | ||
| 169 : | <li>Press 'Finish'.</li> | ||
| 170 : | </ol> | ||
| 171 : | <p>You have now established the target site. Changes you make in the workspace | ||
| 172 : | will be compared to the target and delta will be computed when upload is needed.</p> | ||
| 173 : | <p>To upload, select the project and use 'Team->Synchronize with target' | ||
| 174 : | option. This will bring the familiar 'Synchronize' view used with CVS | ||
| 175 : | repositories. Select the desired branch or the root and 'Upload' the content to | ||
| 176 : | the server.</p> | ||
| 177 : | <p>You can test the remote server by creating a bookmark in the Update Manager | ||
| 178 : | and entering the remote (http://<remote server address>/<project | ||
| 179 : | name>/[site.xml]) address. You should be able to browse the site and see the | ||
| 180 : | same content as when browsing locally (using 'file://' protocol) albeit somewhat | ||
| 181 : | slower (this time Update is downloading content using http protocol). If you can | ||
| 182 : | see it, that means everybody else that can see your server can also create the | ||
| 183 : | bookmark and browse the site contents.</p> | ||
| 184 : | <h3>Building multiple versions</h3> | ||
| 185 : | <p>Since version information is not included in the project name, your workspace | ||
| 186 : | can only hold one set of versions at a time. In contrast, update site can host | ||
| 187 : | many feature and plug-in versions. </p> | ||
| 188 : | <p>You can use the update site support in PDE to build multiple versions, but | ||
| 189 : | you need to perform a little 'trick'. When creating Update Site project, you | ||
| 190 : | need to create it somewhere outside your single-version workspaces. Allocate a | ||
| 191 : | place on your hard drive on the site and create a the project there. You need to | ||
| 192 : | do this for each workspace you want to work in. Note that 'New' wizard for the | ||
| 193 : | update site will not create folders and files (including site.xml) that are | ||
| 194 : | already present in the selected location.</p> | ||
| 195 : | <p>Since your 'features' and 'plugins' folders will contain JARs created in | ||
| 196 : | other workspaces, you should not use 'Scrub output folders before build' option | ||
| 197 : | (Build page in the site editor). Otherwise, you will loose all the JARs that do | ||
| 198 : | not belong to the workspace. When this option is not selected, new JARs will be | ||
| 199 : | created as usual but the old ones will be left alone.</p> | ||
| 200 : | <p>When hosting multiple versions, classification using categories is very | ||
| 201 : | important. Note that a feature can be added to more than one category (just | ||
| 202 : | check as many as you want).</p> |
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |