Initial commit
This commit is contained in:
Eagle517
@@ -0,0 +1,220 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<title>Eclipse 3.0 M2 News</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<table border="0" cellpadding="10" cellspacing="0">
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">Introduction of new properties in the build.properties file of feature</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">When building an eclipse based product from features, it is now possible to copy files or directories to the eclipse directory. This is achieved thanks to the following properties:
|
||||
<ul>
|
||||
root=a comma separated list of files and directories
|
||||
</ul>
|
||||
To refer to a file prefix the name with "file:", to refer to a directory, simply list the name.
|
||||
<P>
|
||||
It is also possible to set permissions on those root files:
|
||||
<ul>
|
||||
root.permissions.XXX=a comma separated list of files and directories
|
||||
</ul>
|
||||
where XXX is a unix chmod style permission description.
|
||||
|
||||
|
||||
It is also possible to copy files and apply permissions on a configuration basis
|
||||
<ul>
|
||||
root.configName=
|
||||
root.configName.permissions.XXX=
|
||||
</ul>
|
||||
where configName is a doted description of the platform (os.ws.arch).
|
||||
|
||||
Here an example for org.eclipse.platform
|
||||
<ul>
|
||||
root=eclipse
|
||||
root.macosx.carbon.ppc=macosx.carbon,../../plugins/platform-launcher/bin/macosx
|
||||
root.macosx.carbon.ppc.link=Eclipse.app/Contents/MacOS/eclipse,eclipse
|
||||
root.macosx.carbon.ppc.permissions.755=Eclipse.app/Contents/MacOS/eclipse
|
||||
</ul>
|
||||
|
||||
|
||||
It is also possible to trigger the generation of source features and plugins
|
||||
<ul>
|
||||
generate.feature@nameOfTheFeatureToGenerate=featureName, plugin@XXXX
|
||||
</ul>
|
||||
generate a feature called 'nameOfTheFeatureToGenerate' from the plugins contained in the feature called 'featureName' and also include the plugin xxxx
|
||||
|
||||
<ul>
|
||||
Example : generate.feature@org.eclipse.jdt.source=org.eclipse.jdt, plugin@org.eclipse.jdt.doc.isv</font></p>
|
||||
</ul>
|
||||
</td>
|
||||
|
||||
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">
|
||||
Introduction of new properties in the build.properties file of plugin</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">
|
||||
|
||||
For every jar file that is being built three variables can be provided. Note that "{jarname}" describes the name of the jar file including its path relative to the project.
|
||||
<ul>
|
||||
<li>a variable named "source.{jarname}" describing where the source of the jar
|
||||
can be found. The expected value is a path relative to the project (for example "src/").</li>
|
||||
|
||||
<li>a variable named "output.{jarname}" describing where the bin of the jar can
|
||||
be found. The expected value is a path relative to the project (for
|
||||
example "bin/").</li>
|
||||
|
||||
<li>a variable named "extra.{jarname}" describing the list of jars required to
|
||||
compile this jar. The expected values are paths relative to the place where the
|
||||
project is.</li>
|
||||
</ul>
|
||||
A short way to explain the content of those variables is to see them as variables used for the compilation:
|
||||
<ul>
|
||||
<li>the source indicates where to find the source of the jar.</li>
|
||||
<li>the extra gives extra values to be put at the end of the classpath when we
|
||||
are compiling the source.</li>
|
||||
<li>the output indicates where the content of a compiled version of the library
|
||||
exists (this is typically used in the classpath of plugins requiring this jar).</li>
|
||||
|
||||
|
||||
</font></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
|
||||
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">Setting permissions on a per basis plugin</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">During a build it is now possible to set permissions and create links on a per plugin basis. Those information are listed in a file called permissions.properties provided at the root of the plugin (as a sibling of build.properties). The format of the file is as follow:
|
||||
<ul><ol>permissions.executable=list of files </ol>
|
||||
<ol>permissions.link=list of files</ol>
|
||||
<ol>permissions.XXX=list of files</ol>
|
||||
</ul>
|
||||
</font></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
|
||||
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">Enhancement of the map file</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">The map file entries have been enhanced to allow plugins and features to be located anywhere in a cvs repository.<p>
|
||||
feature|fragment|plugin@elementID=versionName,CVSRepository,passwordInfo,pathInTheRepository (no starting slash)
|
||||
<p>
|
||||
example:
|
||||
feature@com.foo=v101,:pserver:anon@foo.com:/home/cvs,,a/b/foo-feature</font></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">New properties introduced to control the compilation of plugins</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">
|
||||
|
||||
javacSource: Give the format of the source code. Legal values are 1.3 and 1.4.<br>
|
||||
javacTarget: Generate class files for specific VM version.<br>
|
||||
javacFailOnError: Indicates whether the build will continue even if there are compilation errors.<br>
|
||||
javacDebugInfo: Indicates whether source should be compiled with debug information.<br>
|
||||
javacVerbose: Asks the compiler for verbose output.<br>
|
||||
bootclasspath: Set the classpath of the jdk you compile against.<br>
|
||||
|
||||
All those properties are surfaced in the pde ui.</font></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">Reusable automated build process</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">The new pde build process ease the creation of automated build process by providing a set of template scripts and a general script. Those scripts and templates are used to build the 3.0 build of eclipse (see the project org.eclipse.releng.eclipsebuilder). A small example of their usage is also provided in the feature folder of the plugin.
|
||||
</font></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
<tr>
|
||||
<td colspan="2">
|
||||
<hr>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="30%" valign="top" align="left">
|
||||
<p align="right"><b><font face="Verdana" size="2">Filling version numbers of features</font></b></p>
|
||||
<td width="70%" valign="top" align="left">
|
||||
<p><font face="Verdana" size="2">In the features, version numbers for nested features and plugins can now be specified to 0.0.0 and will be filled in by the appropriate values by the pde build engine.
|
||||
</font></p>
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</table>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -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