Jump to: navigation, search

Difference between revisions of "Using Policy Files"

m
m
 
(8 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Policy files allow a user to configure where to search for updates to a feature when checking for updates. This allows one to update from a different site than the one specified in the feature.xml files.
+
=Eclipse 3.4 p2 Note=
 +
 
 +
Using Policy files for "[[Using_Policy_Files#mirrorControl|mirror control]]" is obsoleted by [[Equinox p2]], available in Eclipse 3.4.
 +
 
 +
To avoid reaching mirrors specified for a particular update site / repository, there are two ways:
 +
 
 +
* If you are in control of the repo, you can remove the mirroring information to make the site unaware of any remote mirrors.
 +
 
 +
<site pack200="true"
 +
  digestURL="http://download.eclipse.org/modeling/emf/updates/milestones/"
 +
  mirrorsURL="http://www.eclipse.org/downloads/download.php?file=/modeling/emf/updates/milestones/site.xml&amp;format=xml">
 +
 
 +
becomes
 +
 
 +
<site pack200="true">
 +
 
 +
* If you are not in control of the repo, you can tell the [[Equinox_p2_director_application|p2 director]] to ignore mirrors:
 +
 
 +
-vmargs -Declipse.p2.mirrors=false
 +
 
 +
See also: {{bug|241430}}, {{bug|236762}}.
 +
 
 +
=Usage=
 +
 
 +
Policy files allow a user to configure where to search for updates to a feature when checking for updates.
 +
 
 +
Why would you want this?
 +
 
 +
* <span id="mirrorControl">'''For mirror control'''. With a policy file you can force your users to update from a mirror within your organization's firewall, instead of letting them choose a public mirror. This might give better performance or at least let you monitor the bits being transferred. Of course you'd have to [http://www.eclipse.org/downloads/mir_request.php be an Eclipse mirror] first.</span>
 +
 
 +
* <span id="testing">'''For testing'''. If your features point to one update site (eg., for Releases) and you want to test doing an update from an old Release to a current Integration build, but that Integration build is not listed on the Releases site. For example, EMF uses [http://download.eclipse.org/modeling/emf/updates/site.xml http://download.eclipse.org/modeling/emf/updates/] for Releases and [http://download.eclipse.org/modeling/emf/updates/site-interim.xml http://download.eclipse.org/modeling/emf/updates/site-interim.xml] for all other builds (I, M, S). </span>
 +
 
 +
* <span id="patching">'''For patching'''. With a policy file you can update a publicly available EPL'd feature with your own custom version. Bear in mind doing so still must be done in adherence to EPL rules. See [http://www.eclipse.org/legal/ http://www.eclipse.org/legal/].</span>
  
 
==Creating the Policy File==
 
==Creating the Policy File==
Line 6: Line 38:
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <update-policy>
 
  <update-policy>
   <url-map pattern="feature.id" url="<nowiki>http://hostname/update/nightly/policy.xml</nowiki>"/>
+
   <url-map pattern="feature.id" url="<nowiki>http://hostname/update/nightly/nightlySite.xml</nowiki>"/>
 
  </update-policy>
 
  </update-policy>
  
In this example, we save this to an XML file named "policy.xml". This is then placed next to the corresponding update site.xml. This effectively says "when I see feature with id x, instead go to update site y rather than the default". You can also use wildcards, such as feature.id.* if you have multiple features with the same prefix.
+
In this example, we save this to an XML file named "policy.xml". This is then placed next to the corresponding update site.xml. This effectively says "when I see feature with id x, instead go to update site y rather than the default". The pattern attribute is a string that represents prefix of a feature ID (up to and including a complete ID). A value of "<tt>*</tt>" matches '''all''' features. For example, a pattern of "<tt>org.eclipse</tt>" will match <tt>org.eclipse.jdt</tt> and <tt>org.eclipse.swt</tt> but '''not''' <tt>com.mycompany.myproduct</tt>
 +
 
 +
Note that the wildcard does not work embedded within a larger pattern; it can only be used by itself. For example, a pattern like "<tt>org.*</tt>" does '''not''' match all plugins that start with <tt>org</tt>
 +
 
 +
===Example===
  
If you wanted to update from a non-standard update site, you could use a policy file to redirect from the default Update site to a secondary one. For example:
+
If you wanted to update all features from a non-standard update site, you could use a policy file to redirect from the default Update site to a secondary one. For example:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?xml version="1.0" encoding="UTF-8"?>
Line 32: Line 68:
 
An additional thought is to provide a preference page to allow the end user to choose which "release stream" they wish to subscribe to. In this case, there is a radio button that might specify "stable", "rc" and "nightly". Selecting one of these radio buttons would automatically set the policy file behind the scenes.
 
An additional thought is to provide a preference page to allow the end user to choose which "release stream" they wish to subscribe to. In this case, there is a radio button that might specify "stable", "rc" and "nightly". Selecting one of these radio buttons would automatically set the policy file behind the scenes.
  
[[Category:Releng]] [[Category:Coordinated]] [[Category:Europa]]
+
[[Category:Releng]] [[Category:Coordinated]] [[Category:Ganymede]] [[Category:Europa]]

Latest revision as of 11:59, 13 February 2009

Eclipse 3.4 p2 Note

Using Policy files for "mirror control" is obsoleted by Equinox p2, available in Eclipse 3.4.

To avoid reaching mirrors specified for a particular update site / repository, there are two ways:

  • If you are in control of the repo, you can remove the mirroring information to make the site unaware of any remote mirrors.
<site pack200="true"
  digestURL="http://download.eclipse.org/modeling/emf/updates/milestones/"
  mirrorsURL="http://www.eclipse.org/downloads/download.php?file=/modeling/emf/updates/milestones/site.xml&format=xml">

becomes

<site pack200="true">
  • If you are not in control of the repo, you can tell the p2 director to ignore mirrors:
-vmargs -Declipse.p2.mirrors=false

See also: bug 241430, bug 236762.

Usage

Policy files allow a user to configure where to search for updates to a feature when checking for updates.

Why would you want this?

  • For mirror control. With a policy file you can force your users to update from a mirror within your organization's firewall, instead of letting them choose a public mirror. This might give better performance or at least let you monitor the bits being transferred. Of course you'd have to be an Eclipse mirror first.
  • For patching. With a policy file you can update a publicly available EPL'd feature with your own custom version. Bear in mind doing so still must be done in adherence to EPL rules. See http://www.eclipse.org/legal/.

Creating the Policy File

A sample policy file is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<update-policy>
  <url-map pattern="feature.id" url="http://hostname/update/nightly/nightlySite.xml"/>
</update-policy>

In this example, we save this to an XML file named "policy.xml". This is then placed next to the corresponding update site.xml. This effectively says "when I see feature with id x, instead go to update site y rather than the default". The pattern attribute is a string that represents prefix of a feature ID (up to and including a complete ID). A value of "*" matches all features. For example, a pattern of "org.eclipse" will match org.eclipse.jdt and org.eclipse.swt but not com.mycompany.myproduct

Note that the wildcard does not work embedded within a larger pattern; it can only be used by itself. For example, a pattern like "org.*" does not match all plugins that start with org

Example

If you wanted to update all features from a non-standard update site, you could use a policy file to redirect from the default Update site to a secondary one. For example:

<?xml version="1.0" encoding="UTF-8"?>
<update-policy>
  <url-map pattern="*" url="http://download.eclipse.org/modeling/emf/updates/site-interim.xml"/>
</update-policy>

Using the Policy File

In Eclipse, navigate to Window > Preferences > Install/Update, and paste in the URL to the policy file and hit OK, eg:

http://download.eclipse.org/modeling/mdt/updates/policy.xml
or, for a local file:
file:///home/nickb/workspace2/modeling/mdt/updates/policy.xml

The next time you search for updates, Eclipse will use the URL specified in the policy file, instead of what's in the feature.xml files.



An additional thought is to provide a preference page to allow the end user to choose which "release stream" they wish to subscribe to. In this case, there is a radio button that might specify "stable", "rc" and "nightly". Selecting one of these radio buttons would automatically set the policy file behind the scenes.