Adding Files to the Root of a Build

Root files are files that must be packaged with an Eclipse install but are not features or plug-ins. Common examples are the eclipse executable and ini files as well as licensing files.
Root files are contributed to a build by features containing the appropriate root properties.

Root file Properties

root
 Specify a list comma separated list of files or folders to be included in all configurations being built.
Relative paths are relative to the containing feature. Use "file:" to specify a file and "absolute:" to use an absolute path.
Examples:
  • root=rootfiles: A relative path to a folder, the contents of the folder are included
  • root=file:license.html,licenses: A relative path to a "license.html" file, and a relative path to a "licenses" folder
  • root=absolute:/eclipse/rootfiles: An absolute path to a folder, the contents of the folder are included
  • root=absolute:file:/eclipse/about.html,file:lib/*.so*: An absolute path to include "about.html", as well as a relative path to include all the *.so* files under the lib folder.

Each comma separated entry becomes an ant fileset. If the entry refers to a folder, then that folder is the "dir" parameter of the fileset and a "**" is used as the "includes" parameter. If the entry is a file, then the containing directory of the file becomes the "dir" parameter and the file is specified in the "includes" parameter.

For all relative files, the property ${baseDir} will be used in the directory. This ${baseDir} property will be feature's root directory where the generated build.xml file will be located.

 
root.<config>
 Specify a list of files or folders to be included for the given configuration. Configurations specified here should correspond to configurations in the configs property for the build. Relative paths are relative to the containing feature. The same "file:" and "absolute:" prefixes used in the "root" property also apply here.
Examples:
  • root.win32.win32.x86=rootfiles: A relative path to a folder, the contents of the folder are included in the win32.win32.x86 configuration
  • root.linux.gtk.x86=absolute:file:about.html: An absolute path to a file to include in the linux.gtk.x86 configuration.
 
root.folder.<subfolder>

root.<config>.folder.<subfolder>
 Similar to the "root" and "root.<config>" properties, except that instead of being copied into the root of the eclipse install, files and folders are instea copied into the given subfolder.
Relative paths are relative to the containing feature. The same "file:" and "absolute:" prefixes used in the "root" property also apply here.
Examples:
  • root.folder.docs/html=html_files: The contents of the feature's "html_files" folder are copied into the docs/html folder in the eclipse install.
  • root.linux.gtk.x86.folder.jre=absolute:/build/jres/linux: An absolute path, the contents of the /build/jres/linux folder are copied into the jre folder of the eclipse install.
These properties are used by PDE/UI when a JRE is specified in a .product file for export. PDE/Build does not currently support including a JRE using the .product file, and these properties would need to be specified in a feature in to include a JRE in a headless product build. 
root.permissions.<rights>

root.<config>.permissions.<rights>
 Specify a list of files to on which to run the ant chmod task. The value of this property will be passed to the ant chmod task as the "includes" parameter. This means that ant wildcard patterns can be used.
Examples:
  • root.permissions.755=eclipse: Set the 'eclipse' file to have executable permissions.
  • root.linux.gtk.x86.permissions.755=lib/**: Set all files under the lib directory to be executable

The <rights> portion of the property is actually passed to the ant chmod task as the "perm" parameter. If the final archive format for the configuration is antTar, then the <rights> format is also passed to an ant tarfileset as the "filemode" parameter. Similarly, for antZip and zipfileset. While the ant chmod task supports permissions such as "og-rwx" (make non-owners unable to touch the file), the tar and zip filesets only support 3 digit octal strings.		 
root.link

root.<config>.link
 List by pairs (separated by comma) the files and folders that need to be symbolically linked. The first entry of the pair is the target and the second entry is the link name..
Example:
  • root.macosx.carbon.ppc.link=Eclipse.app/Contents/MacOS/eclipse,eclipse: In the macosx.carbon.ppc configuration create a softlink in the root named "eclipse" that points to the "Eclipse.app/Contents/MacOS/eclipse" file.

This results in an ant exec task that executes an "ln -sf" command. Given a value of "targetA, nameA, targetB, nameB, targetC, nameC", a set of "ln" commands will be executed in the folder where the eclipse rootfiles are collected: 
		ln -sf targetA nameA
ln -sf targetB nameB
ln -sf targetC nameC

Including Root Files in a Product Build

When using a .product file based on features, then rootfiles can be added to the product simply by specifying the above rootfile properties in any of the included features.

It is possible to include a feature solely for the purpose of contributing rootfiles. If this "rootfile" feature does not specify a "bin.includes" property in its build.properties file, then it will not be included in the final build results, but its contributed rootfiles will be.

When a .product file is based on plug-ins instead of features, rootfiles can still be added to the build. In a product build, PDE/Build automatically generates a container feature which includes all the plug-ins specified in the .product file (See the eclipse.generateFeature task). There are two ways to add rootfiles to this product build: