Initial commit
This commit is contained in:
Eagle517
@@ -0,0 +1,252 @@
|
||||
<!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>
|
||||
Reference in New Issue
Block a user