| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> |
| <html> |
| <head> |
| <meta name="copyright" |
| content="Copyright (c) IBM Corporation and others 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."> |
| <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>Repackaging Eclipse Components</title> |
| </head> |
| <body style="background-color: rgb(255, 255, 255);"> |
| <h1>Packaging Eclipse Components<br> |
| </h1> |
| <p>Eclipse components are delivered as archive files. Each archive |
| contains a collection of features and plug-ins. Typically the archives |
| contain all the functions that a particular component has to offer. It |
| is |
| often the case that consumers either need more than one component |
| and/or only need parts of some components. Without assistance, |
| consumers would have to manually fetch the archives containing the |
| superset |
| of the function they need and then manually extract the required |
| features and plug-ins. This can be a laborious and error prone process.</p> |
| <p>Fortunately, PDE contains a batch oriented mechanism, the <em>packager</em> |
| which can help. In short, the packager takes as input a list of |
| archives containing features and a list of interesting features. It |
| then fetches |
| the zips, extracts the features (and their plug-ins) and repackages |
| them into an output zip.</p> |
| <h2>Quick Start<br> |
| </h2> |
| <p>Below is a set of basic steps to get started with the |
| packager. It is suggested that you build *nix packages on a *nix |
| machine to ensure that file permissions are preserved.<br> |
| </p> |
| <ol> |
| <li>Create a packaging configuration directory and copy the template |
| files (packager.properties, packaging.properties, and |
| customTargets.xml) from org.eclipse.pde.build/templates/packager here.</li> |
| <li>Edit the copied packager.properties files and set the following |
| properties:</li> |
| <ul> |
| <li><span style="font-weight: bold;">baseDirectory </span>: the |
| directory in which the actual packaging work will take place. |
| <br> |
| </li> |
| <li><span style="font-weight: bold;">featureList </span>: a comma |
| separated list of feature ids that you wish to include in your archive.<br> |
| </li> |
| <li><span style="font-weight: bold;">componentFilter </span>: |
| A comma separated list of components from which your features can be |
| found. Specifying this will avoid unnecessary downloads. |
| Use * if you don't know the components. (See the componentName in |
| the <a href="pde_packager.htm#Packager_Map_File_Format">Packager Map |
| File Format</a> |
| below).<br> |
| <span style="font-weight: bold;"></span></li> |
| <li><span style="font-weight: bold;">contentFilter</span> : A comma |
| separated list of content type you are interested in. Common |
| content types are <tt>runtime</tt> or <tt>sdk</tt>. This is |
| used to optimize the |
| downloading of the archives. Leave this blank to not filter |
| on content type. (See the contentDescription in the <a |
| href="#Packager_Map_File_Format">Packager Map File Format</a> |
| below).</li> |
| <li><span style="font-weight: bold;">config </span>: The |
| configurations to package. This is an "&" separated list of comma |
| separated triples of operating system, |
| windowing system and architecture (eg <tt>win32,win32,x86 & linux, |
| gtk, ppc</tt>)</li> |
| </ul> |
| <li>Get packager map files. The following properties control |
| downdloading the map files:<br> |
| <ul> |
| <li><span style="font-weight: bold;">localMaps</span> : Set this |
| property if you have map files locally, |
| put |
| the map files in <tt>${downloadDirectory}</tt> (by default this is <tt>${baseDirectory}/toPackage</tt>). |
| Comment out this property to automatically download the map file.</li> |
| <li><span style="font-weight: bold;">packagerMapURL</span> : The |
| URL from which to download the map file.</li> |
| </ul> |
| The packager script will concatenate all *.map files found in <tt>${downloadDirectory}</tt>. |
| To download more than one map file, or to fetch them from CVS edit the |
| customTargets.xml file and change the getMapFiles target. </li> |
| <li>Run the packager using the following command:</li> |
| <pre>java -jar <eclipse install>/plugins/org.eclipse.equinox.launcher_<version>.jar -application org.eclipse.ant.core.antRunner <br> -buildfile <<eclipse install>/plugins/org.eclipse.pde.build_<version>/scripts/package.xml> <br> -DpackagingInfo=<path to your packaging configuration directory><br></pre> |
| </ol> |
| <h2><a name="Packager_Map_File_Format"></a>Packager Map File Format</h2> |
| The packager map files are used to describe the various archives, their |
| content and where they can be downloaded from. They are similar |
| to the map files used in the build process to fetch bundles from |
| repositories. The format of a packager map file entry is as |
| follows:<br> |
| <div style="text-align: center;"><tt>archiveName |
| = <span style="font-weight: bold;">url</span> | [<span |
| style="font-weight: bold;">configList</span>] | |
| [<span style="font-weight: bold;">directory</span>] | <span |
| style="font-weight: bold;">contentDescription</span> | <span |
| style="font-weight: bold;">componentName</span></tt><br> |
| </div> |
| <ul> |
| <li><span style="font-weight: bold;">archiveName </span>: This is |
| the name of the archive<br> |
| <span style="font-weight: bold;"></span></li> |
| <li><span style="font-weight: bold;">url</span> : This is the url |
| where the archive can be found. The concatenation of url and |
| archiveName should point to the archive to download.</li> |
| <li><span style="font-weight: bold;">configList</span> : This is an |
| "&" separated list of configs that this archive contains. |
| (eg: <tt>win32, win32, x86 & linux, gtk, x86</tt>). If no |
| value is given the archive is considered to be platform independant.</li> |
| <li><span style="font-weight: bold;">directory</span> : The directory |
| where the content of the archive should be extracted relative to a |
| standard eclipse installation. When no value is specified it |
| means that the archive contains an eclipse installation directory at |
| its |
| root.<br> |
| <span style="font-weight: bold;"></span></li> |
| <li><span style="font-weight: bold;">contentDescription</span> : The |
| content flags indicating the type of content in this archive. |
| Normally this is something like <tt>runtime</tt>, <tt>sdk</tt>, <tt>source</tt>, |
| <tt>doc</tt>, etc.</li> |
| <li><span style="font-weight: bold;">componentName</span> : The |
| canonical name of the component this archive is for. For example |
| eclipse, jdt, cdt, gef, emf, etc.<br> |
| </li> |
| </ul> |
| <br> |
| Note that configList and directory are optional, it is important that |
| the appropriate number "|" separators are still used.<br> |
| Examples:<br> |
| <pre>eclipse-SDK-3.1-win32.zip=http://download.eclipse.org/downloads/drops/R-3.1-200506271435/ | win32,win32,x86 | | sdk | eclipse<br>eclipse-PDE-3.1.zip=http://download.eclipse.org/downloads/drops/R-3.1-200506271435/ | | | runtime | pde<br></pre> |
| <h2>Packager Configuration Properties</h2> |
| The following properties can be set in the packager configuration |
| packager.properties file:<br> |
| <table style="width: 90%; text-align: left; margin-left: 40px;" |
| border="1" cellpadding="2" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;">baseDirectory<br> |
| </td> |
| <td style="vertical-align: top;">The directory in which all the |
| packaging will take place<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">workingDirectory<br> |
| </td> |
| <td style="vertical-align: top;">The directory in which the |
| scripts will be generated. The value in the template is <tt>${baseDirectory}/workingPlace</tt><br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">downloadDirectory<br> |
| </td> |
| <td style="vertical-align: top;">The folder to which the archives |
| will be downloaded. The value in the template is <tt>${baseDirectory}/toPackage</tt><br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">tempDirectory<br> |
| </td> |
| <td style="vertical-align: top;">The folder that the archives |
| will be extracted to. The value in the template is <tt>${baseDirectory}/temp</tt><br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">featurePaths<br> |
| </td> |
| <td style="vertical-align: top;">The name of the root of the |
| archives downloaded. The value in the template is <tt>eclipse</tt>.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">featureList<br> |
| </td> |
| <td style="vertical-align: top;">A comma separated list of |
| feature ids that you wish to repackage.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">componentFilter<br> |
| </td> |
| <td style="vertical-align: top;">A comma separated list of the |
| components from which the features in featureList can be found. |
| This filters the available archives and allows the packager to optimize |
| the set of files downloaded.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">contentFilter<br> |
| </td> |
| <td style="vertical-align: top;">A comma separated list of |
| content types to fetch. This filters the set of available |
| archives and allows the packager to optimize the set of files |
| downloaded.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">config<br> |
| </td> |
| <td style="vertical-align: top;">An "&" seperated list of |
| configs (comma separated triples of operating system, windowing system, |
| architecture) to repackage. (eg: <tt>win32, win32, x86 & |
| linux, gtk, x86</tt>) </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">archivesFormat<br> |
| </td> |
| <td style="vertical-align: top;">The formats of the |
| archives. An "&" separated list of config - format. |
| (eg: <tt>win32, win32, x86 - antZip & linux, gtk, ppc - tar</tt>). |
| If |
| no archive format is specified for a given config, the default format |
| is antZip.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">zipargs<br> |
| </td> |
| <td style="vertical-align: top;">Extra arguments to be passed to |
| zip<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">unzipargs<br> |
| </td> |
| <td style="vertical-align: top;">Extra arguments to be passed to |
| unzip<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">archivePrefix<br> |
| </td> |
| <td style="vertical-align: top;">The prefix of the resulting |
| archive(s)<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">collectingFolder<br> |
| </td> |
| <td style="vertical-align: top;">The name of the root folder of |
| the resulting archive.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">buildId<br> |
| </td> |
| <td style="vertical-align: top;">Controls the build id in the |
| default name of the archive.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">buildType<br> |
| </td> |
| <td style="vertical-align: top;">Type of the build, used in |
| naming the build output. Typically one of I, N, M, S, ...<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">buildLabel<br> |
| </td> |
| <td style="vertical-align: top;">Label for the build. The |
| template value is <tt>${buildType}.${buildId}</tt><br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">archiveNamePrefix<br> |
| </td> |
| <td style="vertical-align: top;">Control the name of the |
| resulting archive. The default value of this is <tt>${buildId}</tt><br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">packagingProperties<br> |
| </td> |
| <td style="vertical-align: top;">A relative path to the file |
| containing the properties packaging root files.. By default |
| this points to packaging.properties.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">deltaPack<br> |
| </td> |
| <td style="vertical-align: top;">Whether or not to generate a |
| delta pack. This will exclude platform independant pieces and |
| will group all configs into one archive.<br> |
| </td> |
| </tr> |
| <tr> |
| <td style="vertical-align: top;">unzipOrder<br> |
| </td> |
| <td style="vertical-align: top;">a comma separated list of archive name prefixes setting |
| the order in which archives should be extracted.<br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| <h2>Packaging Root Files</h2> |
| In the packager configuration packager.properties file, the property |
| packagingProperties points to a property file which specifies the root |
| files that need to be packaged. By default this is the file |
| packaging.properties.<br> |
| <br> |
| This property file should contain the properties specifying the |
| required root files. See the <a |
| href="../../reference/pde_feature_generating_build.htm#Feature_specific_properties">Feature |
| specific properties</a> page for details on the root properties.<br> |
| <br> |
| </body> |
| </html> |
