Fetch
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: element@element_id=tag,:connection_type:user@host:repository
Examples:
Generate Scripts
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.
Build
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.
Generate Scripts
In order to generate build.xml scripts for some
element, it is necessary to use the org.eclipse.pde.core.script
application extension point provided by PDE Core. The arguments for this
application are:
Examples:
(1) java -cp startup.jar org.eclipse.core.launcher.Main
-application org.eclipse.pde.core.buildScript
-elements plugin@org.eclipse.core.resources
-install c:\mybuild\
(2) java -cp startup.jar org.eclipse.core.launcher.Main
-application org.eclipse.pde.core.buildScript
-elements plugin@org.eclipse.core.resources,fragment@my.fragment
-install c:\mybuild\
(3) java -cp startup.jar org.eclipse.core.launcher.Main
-application org.eclipse.pde.core.buildScript
-elements feature@org.eclipse.platform.feature
-nochildren
-install c:\mybuild\
...
[explain the ant task as well]
...
build.properties
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:
custom = yes
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.
bin.includes =
bin.excludes =
jar.external =
source.<jar_name>=<source_locations>
Indicates, for the specified jar, where to find
its source. The source_locations is a comma-separated list of [element-relative?]
locations. Plug-ins [elements?] requiring
compilation must define this entry.
Example:
source.resources.jar = src/
zip.external =
zip.program =
zip.argument =
${zip.file}
jars.compile.order =
build variables
There are currenttly 4 build variables: os, ws,
nl and arch. The build.properties file or a custom build.xml
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}.
In the build.properties file, they can
be used as follows:
${os/linux}.bin.includes = src/linux
Indicates that the folder
src/linux should be include to the bin target if os=linux .
${os/linux,ws/motif}.bin.includes = src/linux
Indicates that the folder
src/linux should be include to the bin target if os=linux and ws=motif
.
${ws/motif}.bin.includes = src/motif
Indicates that the folder
src/motif should be include to the bin target if ws=motif.
Feature targets:
all.children
Calls plugin-template and fragment-template.
all.plugins
Delegates target calls to all the feature's plug-ins.
all.fragments
Delegates target calls to all the feature's fragments.
build.jars
Generates the required jars for the feature and
its children.
build.sources
Creates all the *src.zip files corresponding to
this feature's jars and its children. E.g. for startup.jar, it creates
startupsrc.zip .
build.update.jar
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.
gather.bin.parts
Copies all feature relevant parts (defined by bin.includes
and bin.excludes) to ${destination}/install/features/${feature}.
gather.logs
Copies *.log files to ${destination}/install/features/${feature}.
gather.sources
Copies files generated by build.sources (*src.zip)
to ${destination}/install/features/${feature}.
Plug-ins and fragments targets:
build.jars
Generates the required jars for this plugin/fragment.
build.sources
Creates all the *src.zip files corresponding to
this element's jars. E.g. for resources.jar, it creates resourcessrc.zip
.
build.update.jar
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.
clean
Cleans all temp files and folders plus files created
by the script targets (e.g. *.jar, *.zip, ...).
gather.bin.parts
Copies all plugin relevant parts (defined by bin.includes
and bin.excludes) to ${destination}/(plugins | fragments)/(${plugin}
| ${fragment}). E.g., ${destination}/plugins/${plugin}.
gather.logs
Copies *.log files to ${destination}/(plugins |
fragments)/(${plugin} | ${fragment}). E.g., ${destination}/plugins/${plugin}.
gather.sources
Copies files generated by build.sources (*src.zip)
to ${destination}/(plugins | fragments)/(${plugin} | ${fragment}). E.g.,
${destination}/plugins/${plugin}.
To be implemented: