252 lines
13 KiB
HTML
252 lines
13 KiB
HTML
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<title>Using PDE Core to build Plug-ins, Fragments and Features</title>
|
|
</head>
|
|
<body>
|
|
|
|
<h2>What is PDE Build?</h2>
|
|
|
|
PDE Build is a plug-in that helps users build their own plug-ins. The term build here is related to deployment
|
|
and not development. PDE Build takes an Eclipse Plug-in Project, its plugin.xml and build.properties
|
|
files and generates a build.xml script to be run by Ant. Building plug-ins, fragments or features consists of the
|
|
3 stages: <em>fetch</em>, <em>generate scripts</em> and <em>build</em> 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. "Directory files" or "map files" are responsible for identifying
|
|
where, how and which plug-ins should go to the build machine. These files are basically Java properties files
|
|
where the entries have the following format:
|
|
<p>
|
|
|
|
<tt> element@element_id=tag,:connection_type:user@host:repository</tt>
|
|
<p>
|
|
|
|
The current implementation of fetch only works against CVS repositories and there are no plans for supporting
|
|
different kinds. Skipping or substituting this step should not be hard for users of other VCM systems or other kind
|
|
of storage.
|
|
<p>
|
|
|
|
Examples:
|
|
<p>
|
|
<tt>
|
|
plugin@org.eclipse.pde.build=v20020717, :pserver:anonymous@dev.eclipse.org:/home/eclipse,<br>
|
|
fragment@org.eclipse.core.resources.win32=v20020627, :pserver:anonymous@dev.eclipse.org:/home/eclipse, <br>
|
|
plugin@org.eclipse.platform=v20020820, :pserver:anonymous@dev.eclipse.org:/home/eclipse, <br>
|
|
</tt>
|
|
<p>
|
|
|
|
<b>Generate Ant buildfiles</b><br>
|
|
Once the plug-ins, fragments and features are in
|
|
place, we need to generate the build.xml scripts. These Ant buildfiles drive
|
|
the build process. In order to generate them, PDE Build takes as input the plugin.xml, fragment.xml, feature.xml and build.properties files. The complete
|
|
description of the first three files are elsewhere in the Eclipse documentation. 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. One important thing here is
|
|
to know exactly what targets to call in order to get the desired result.
|
|
<p>
|
|
|
|
<h2>How do I use PDE Build?</h2>
|
|
|
|
<h3>Fetch</h3>
|
|
This step is done by the <code>eclipse.fetch</code>
|
|
Ant task provided by PDE Build. Here is an example:
|
|
|
|
<pre>
|
|
<eclipse.fetch
|
|
scriptName=<font COLOR="#008000">"fetch.xml"</font>
|
|
elements=<font COLOR="#008000">"feature@org.eclipse.platform-feature"</font>
|
|
directory=<font COLOR="#008000">"${basedir}/test.map"</font>
|
|
install=<font COLOR="#008000">"${basedir}/source"</font>
|
|
children=<font COLOR="#008000">"true"</font>
|
|
/>
|
|
</pre>
|
|
|
|
The above task generates an Ant buildfile called <em>fetch.xml</em>. It consists of Ant
|
|
CVS tasks that retrieve the Eclipse Platform feature and all its plug-ins and
|
|
fragments.
|
|
<p>
|
|
|
|
<h2>Generate Scripts</h2>
|
|
<p>
|
|
|
|
Once features, plug-ins and fragments are downloaded you
|
|
need to generate their Ant buildfiles. This step is done by the <code>eclipse.buildScripts</code>
|
|
Ant task provided by PDE Build. Here is an example:
|
|
|
|
<pre>
|
|
<eclipse.buildScript
|
|
elements=<font COLOR="#008000">"feature@org.eclipse.platform-feature"</font>
|
|
install=<font COLOR="#008000">"${basedir}/source"</font>
|
|
children=<font COLOR="#008000">"true"</font>
|
|
/>
|
|
</pre>
|
|
|
|
The above task will generate Ant buildfiles for the
|
|
Eclipse Platform feature and all its plug-ins and fragments.
|
|
<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 (feature, plug-in or
|
|
fragment). It is a simple
|
|
properties file that describes, for example, 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><code>custom = yes</code></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>
|
|
<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 style="margin-top: 0; margin-bottom: 0"> <p style="margin-top: 0; margin-bottom: 0"><b>jars.compile.order =</b>
|
|
<comma separated list of JARs><br> Specifies in what order the
|
|
JARs should be compiled. Should be used to solve build dependencies within the
|
|
same plug-in/fragment.<p style="margin-top: 0; margin-bottom: 0">
|
|
Example:<p style="margin-top: 0; margin-bottom: 0">
|
|
jars.compile.order=resources.jar,lib/resources-ant.jar
|
|
<p>
|
|
|
|
<h2>Build</h2>
|
|
The generated build.xml scripts from the previous step have many targets. The
|
|
public ones described bellow. These are the targets that a custom build.xml script
|
|
<em>must</em> 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.logs</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.logs</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}.
|
|
<p>
|
|
|
|
<h2>General notes on PDE Build</h2>
|
|
|
|
This section is not organized in any way. It just contains
|
|
general knowledge on the use and implementation of the PDE Build plug-in.
|
|
Although it should be up to date there is no guarantee about it. Check with your
|
|
favorite pde build developer before making any assumptions based on it.
|
|
<p>
|
|
|
|
<ul>
|
|
<li>units are features, plug-ins and fragments</li>
|
|
<li>Ant is the base technology</li>
|
|
<li>CVS is the supported repository for the fetch task</li>
|
|
<li>The build basically consists of these steps: fetch, generate buildfiles
|
|
and build. Te steps are triggered by Ant tasks defined by pde build.</li>
|
|
<li>Besides the basic steps any other step can be included by the releng team.
|
|
It will only depend on the bootstrap buildfile. This buildfile is not
|
|
generated by the pde.build.</li>
|
|
<li>Features, plug-ins and fragments can have custom build scripts as long as
|
|
they conform with the API (automatically generated script).</li>
|
|
<li>The Ant buildfiles generate by pde build have to run in 2 different
|
|
environments correctly: headless (Eclipse releng style) and the Eclipse UI.</li>
|
|
<li>When implementing a new functionality or changing an existing one there
|
|
are two modes to consider. One is the build running headless like the releng
|
|
does and the other is the script being executed by a user of Eclipse using the
|
|
external tools UI. They can have completely different characteristics and
|
|
point of views. If one assumption is correct for one of these scenarios it
|
|
does not mean it is correct for the other. One of the fundamental differences
|
|
is that there is no concept of "project" when running headless. PDE Build does
|
|
not even know about the Resources plug-in.</li>
|
|
<li>Buildfiles for features, plug-ins and fragments have to run independently
|
|
of Eclipse since we also support source builds. If possible they should
|
|
contain only the core Ant tasks. Any Eclipse relative task in a buildfile must
|
|
not be a requirement. Only add those in optional targets when extra value for
|
|
the user is needed (e.g. refresh local, JDT compiler, etc.).</li>
|
|
<li>Changing the buildfile is almost like an API change since there are
|
|
plug-ins using their own custom scripts (a good example is SWT). For example,
|
|
renaming a target called build.jars to build.all.jars is a breaking change
|
|
since SWT does not provide such target. Adding targets is also a breaking
|
|
change. Again, it has to be handled like an API change.</li>
|
|
<li>The Java runtime library can be defined by the user setting the
|
|
bootclasspath property (e.g. <property name="bootclasspath" value="c:\runtime\rt.jar"/>.
|
|
This is necessary, for example, when building an Eclipse Windows drop from a
|
|
Linux machine.</li>
|
|
<li>Compile paths in the buildfiles are represented as relative paths when
|
|
possible and full paths otherwise. In order for source builds to work, ALL
|
|
paths have to be relative since it has to be portable to any user that wants
|
|
to build Eclipse. In order to achieve it, the fetch task retrieve the projects
|
|
from CVS in a pre-defined structure. Many places in the pde build code will
|
|
rely on this structure so that changes to it should be considered very
|
|
carefully. The easiest way to understand the structure is to take a look at a
|
|
recent generated fetch script.</li>
|
|
<li>During the Eclipse Platform build the SWT plug-in and its fragments have
|
|
to be built before the platform feature since it is a very special plug-in.
|
|
All the JARs are placed in its platform specific fragments. For example, when
|
|
building Eclipse Platform for Win32, if we build the platform feature first
|
|
there will be no swt.jar since its JAR is built by the swt.win32 fragment and
|
|
it is not part of the base platform feature (it is part of the win32 platform
|
|
feature). So the eclipse.ui plug-in will not build since it depends on SWT and
|
|
the JAR is not there yet.</li>
|
|
<li>Plug-ins and fragments from one feature cannot depend on plug-ins from
|
|
another feature unless one feature depends on the other. For example, a
|
|
plug-in in the JDT feature can depend on a plug-in in the Platform feature but
|
|
not the other way around.</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html> |