| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <meta name="GENERATOR" content="Mozilla/4.7 [en] (WinNT; I) [Netscape]"> | |
| <title>Using PDE Core to build Plug-ins, Fragments and Features</title> | |
| </head> | |
| <body> | |
| <h2> | |
| What is PDE Core?</h2> | |
| PDE Core is a plug-in that helps users building their | |
| own plug-ins. The term building here is related to deployment and not development. | |
| Basically, PDE Core takes an Eclipse Plug-in Project, its plugin.xml and | |
| build.properties files and generate a build.xml script to be run by Ant. | |
| Building plug-ins, fragments or features consists of the 3 stages: fetch, | |
| generate scripts and build that are described bellow. | |
| <p><b>Fetch</b> | |
| <br> Consists of taking the interesting elements from | |
| a repository to the build machine. These elements can be plug-ins, fragments | |
| or features. A file called directory.txt is responsible for identifying | |
| where, how and which plug-ins should go to the build machine. Ths file | |
| is basically a Java properties file where the entries have the following | |
| format: <i>element@element_id=tag,:connection_type:user@host:repository</i> | |
| <br>Examples: | |
| <ul> | |
| <li> | |
| plugin@org.eclipse.pde=v20011211, :pserver:anonymous@dev.eclipse.org:/home/eclipse,</li> | |
| <li> | |
| feature@org.eclipse.jdt=v20011120, :pserver:anonymous@dev.eclipse.org:/home/eclipse,</li> | |
| </ul> | |
| The current implementation of fetch only works against CVS repositories | |
| and there are no plans for supporting different kinds. Skiping or substituting | |
| this step should not be hard for users of other VCM systems or other kind | |
| of storage. | |
| <p><b>Generate Scripts</b> | |
| <br> Once the plug-ins, fragments and features are in | |
| place, we need to generate the build.xml scripts. These Ant scripts drive | |
| the build process. In order to generate them, PDE Core takes as input the | |
| plugin.xml, fragment.xml, feature.xml and build.properties files. The complete | |
| description of the first 3 files are elsewhere. Here we will only fully | |
| describe the build.properties file and relevant parts of the others. | |
| <p><b>Build</b> | |
| <br> This step is basically executed by Ant, although | |
| we do need Eclipse defined tasks and types. One important thing here is | |
| to know exactly what targets to call in order to get the desired result. | |
| <br> | |
| <h2> | |
| How do I use PDE Core?</h2> | |
| <h2> | |
| <b>Fetch</b></h2> | |
| PDE Core provides the <tt>org.eclipse.pde.core.fetch</tt> | |
| application... | |
| <br> ... | |
| <br> explain the ant task as well | |
| <br> ... | |
| <p><b>Generate Scripts</b> | |
| <br> In order to generate build.xml scripts for some | |
| element, it is necessary to use the <tt>org.eclipse.pde.core.script</tt> | |
| application extension point provided by PDE Core. The arguments for this | |
| application are: | |
| <ul> | |
| <li> | |
| <tt>-? | |
| prints usage</tt></li> | |
| <li> | |
| <tt>-buildOS specifies | |
| the value of the os variable</tt></li> | |
| <li> | |
| <tt>-buildWS specifies | |
| the value of the ws variable</tt></li> | |
| <li> | |
| <tt>-buildNL specifies | |
| the value of the nl variable</tt></li> | |
| <li> | |
| <tt>-buildARCH specifies the | |
| value of the arch variable</tt></li> | |
| <li> | |
| <tt>-cvspassfile specifies the location of | |
| the cvspass file</tt></li> | |
| <li> | |
| <tt>-dev <args> plugin relative | |
| development entries to be added to the compile classpath of the elements. | |
| Specially useful when building a specific plug-in but its prerequisites | |
| do not have jars generated yet but are compiled in a folder like pluginFolder/bin.</tt></li> | |
| <li> | |
| <tt>-directory location of the | |
| directory file</tt></li> | |
| <li> | |
| <tt>-elements <arg> list of elements</tt></li> | |
| <li> | |
| <tt>-install <arg> element's location</tt></li> | |
| <li> | |
| <tt>-nochildren feature's children | |
| should not have scripts generated</tt></li> | |
| <li> | |
| <tt>-plugins -</tt></li> | |
| <li> | |
| <tt>-scriptname location of the fetch | |
| script</tt></li> | |
| </ul> | |
| <p><br>Examples: | |
| <p><tt>(1) java -cp startup.jar org.eclipse.core.launcher.Main</tt> | |
| <br><tt> -application org.eclipse.pde.core.buildScript</tt> | |
| <br><tt> -elements plugin@org.eclipse.core.resources</tt> | |
| <br><tt> -install c:\mybuild\</tt> | |
| <p><tt>(2) java -cp startup.jar org.eclipse.core.launcher.Main</tt> | |
| <br><tt> -application org.eclipse.pde.core.buildScript</tt> | |
| <br><tt> -elements plugin@org.eclipse.core.resources,fragment@my.fragment</tt> | |
| <br><tt> -install c:\mybuild\</tt> | |
| <p><tt>(3) java -cp startup.jar org.eclipse.core.launcher.Main</tt> | |
| <br><tt> -application org.eclipse.pde.core.buildScript</tt> | |
| <br><tt> -elements feature@org.eclipse.platform.feature | |
| -nochildren</tt> | |
| <br><tt> -install c:\mybuild\</tt> | |
| <p> ... | |
| <br> [explain the ant task as well] | |
| <br> ... | |
| <br> | |
| <p><b>build.properties</b> | |
| <br> The build mechanism is driven by a build specification. | |
| The specification for an individual plug-in, fragment, or feature is found | |
| in a build.properties file in the corresponding element. It is a simple | |
| properties file that describes where to find the source code for the element. | |
| Other entries describe which files should be included/excluded in/from | |
| various forms of distribution (e.g., binary, source). The possible entries | |
| are described bellow: | |
| <p><b><tt>custom = yes</tt></b> | |
| <br> Tells the script generator that no script is necessary | |
| for the current element. It is usually used when a custom build.xml script | |
| is provided. The build.xml script has to be in the root folder of the element. | |
| <p><b>bin.includes =</b> | |
| <br><b>bin.excludes =</b> | |
| <br><b>jar.external =</b> | |
| <p><b>source.<jar_name>=<source_locations></b> | |
| <br> Indicates, for the specified jar, where to find | |
| its source. The source_locations is a comma-separated list of <b><font color="#CC0000">[element-relative?]</font></b> | |
| locations. Plug-ins <b><font color="#CC0000">[elements?]</font></b> requiring | |
| compilation must define this entry. | |
| <br> Example: | |
| <br> source.resources.jar = src/ | |
| <p><b>zip.external =</b> | |
| <br><b>zip.program =</b> | |
| <br><b>zip.argument =</b> | |
| <br><b>${zip.file}</b> | |
| <br> | |
| <p><b><tt>build variables</tt></b> | |
| <br> There are currenttly 4 build variables: os, ws, | |
| nl and arch. The <tt>build.properties</tt> file or a custom <tt>build.xml</tt> | |
| script can make use of them in order to create platform specific builds. | |
| They can be referenced inside the script as normal Ant properties, whose | |
| values are referenced by ${variable_name}. | |
| <br> In the <tt>build.properties</tt> file, they can | |
| be used as follows: | |
| <p><tt> ${os/linux}.bin.includes = src/linux</tt> | |
| <br> Indicates that the folder | |
| src/linux should be include to the bin target if os=linux . | |
| <p><tt> ${os/linux,ws/motif}.bin.includes = src/linux</tt> | |
| <br> Indicates that the folder | |
| src/linux should be include to the bin target if os=linux and ws=motif | |
| . | |
| <p><tt> ${os/*,ws/motif}.bin.includes = src/motif</tt> | |
| <br> Indicates that the folder | |
| src/motif should be include to the bin target if ws=motif on any OS. | |
| <br> | |
| <br> | |
| <h2> | |
| <b>Build</b></h2> | |
| The generated build.xml scripts from the previous step | |
| have many targets. They public ones described bellow. These are the targets | |
| that a custom build.xml script has to implement. | |
| <p><b><font size=+2>Feature targets:</font></b> | |
| <p><b>all.children</b> | |
| <br> Calls plugin-template and fragment-template. | |
| <p><b>all.plugins</b> | |
| <br> Delegates target calls to all the feature's plug-ins. | |
| <p><b>all.fragments</b> | |
| <br> Delegates target calls to all the feature's fragments. | |
| <p><b>build.jars</b> | |
| <br> Generates the required jars for the feature and | |
| its children. | |
| <p><b>build.sources</b> | |
| <br> Creates all the *src.zip files corresponding to | |
| this feature's jars and its children. E.g. for startup.jar, it creates | |
| startupsrc.zip . | |
| <p><b>build.update.jar</b> | |
| <br> Creates a jar file containing a binary build of | |
| the feature. Source is not included. The jar is in a format supported by | |
| install/update. | |
| <p><b>gather.bin.parts</b> | |
| <br> Copies all feature relevant parts (defined by <b>bin.includes</b> | |
| and <b>bin.excludes</b>) to ${destination}/install/features/${feature}. | |
| <p><b>gather.log</b> | |
| <br> Copies *.log files to ${destination}/install/features/${feature}. | |
| <p><b>gather.sources</b> | |
| <br> Copies files generated by <b>build.sources</b> (*src.zip) | |
| to ${destination}/install/features/${feature}. | |
| <br> | |
| <p><b><font size=+2>Plug-ins and fragments targets:</font></b> | |
| <p><b>build.jars</b> | |
| <br> Generates the required jars for this plugin/fragment. | |
| <p><b>build.sources</b> | |
| <br> Creates all the *src.zip files corresponding to | |
| this element's jars. E.g. for resources.jar, it creates resourcessrc.zip | |
| . | |
| <p><b>build.update.jar</b> | |
| <br> Creates a jar file containing a binary build of | |
| the element. Source is not included. The jar is in a format supported by | |
| install/update. | |
| <p><b>clean</b> | |
| <br> Cleans all temp files and folders plus files created | |
| by the script targets (e.g. *.jar, *.zip, ...). | |
| <p><b>gather.bin.parts</b> | |
| <br> Copies all plugin relevant parts (defined by <b>bin.includes</b> | |
| and <b>bin.excludes</b>) to ${destination}/(plugins | fragments)/(${plugin} | |
| | ${fragment}). E.g., ${destination}/plugins/${plugin}. | |
| <p><b>gather.log</b> | |
| <br> Copies *.log files to ${destination}/(plugins | | |
| fragments)/(${plugin} | ${fragment}). E.g., ${destination}/plugins/${plugin}. | |
| <p><b>gather.sources</b> | |
| <br> Copies files generated by <b>build.sources</b> (*src.zip) | |
| to ${destination}/(plugins | fragments)/(${plugin} | ${fragment}). E.g., | |
| ${destination}/plugins/${plugin}. | |
| <br> | |
| <br> | |
| <p><b><font color="#FF0000">To be implemented:</font></b> | |
| <ul> | |
| <li> | |
| Write comments.</li> | |
| <li> | |
| ant should not pass bin when -dev bin is specified (will require ant hack | |
| or a command line filter)</li> | |
| <li> | |
| create template.xml dinamically</li> | |
| <li> | |
| users should define their own compiler</li> | |
| <li> | |
| users should define their own runtime libraries (rt.jar)</li> | |
| <li> | |
| some build.properties values should be inherited by elements when building | |
| a feature (need to be careful about which ones could be overwritten and | |
| which ones not). Maybe the safest assumptions is to behave like Ant (properties | |
| cannot be set twice - first value set stays)</li> | |
| <li> | |
| add variable that points out the base install dir for plugins, fragments | |
| and features. This variable should be available for the build.xml script. | |
| Basically, SWT wants to build plugin and fragments from one plugin using | |
| their custom build.xml.</li> | |
| <li> | |
| look at problem related to PDE UI and not having plugins in the structure | |
| pde core requires - (can we remove this structure requirement?)</li> | |
| <li> | |
| use temp vars to reduce garbage (specially in cases like getPropertyFormat())</li> | |
| <li> | |
| review error handling</li> | |
| <li> | |
| verify if all messages and exception constants are used otherwise delete | |
| them</li> | |
| <li> | |
| fix the way properties are loaded and overwritten (should be easier and | |
| clearer)</li> | |
| <li> | |
| make sure we are following Ant guidelines wrt our tasks parameters and | |
| their relation to Ant properties</li> | |
| <li> | |
| unify temp folder relative to the ${install} property - should think of | |
| the consequences - multiple simultaneous builds?</li> | |
| <li> | |
| remove all strings and replace by contants when possible</li> | |
| </ul> | |
| </body> | |
| </html> |