Jump to: navigation, search

Difference between revisions of "WTP/Releng/Tools"

< WTP
(Rewrite Licenses)
(Migrate License Support)
Line 50: Line 50:
  
  
The advantages of using this new form of indirect references, is that in the future, very little changes would need to be made, if any, and your features would automatically get the new licenses included.  
+
The advantages of using this new form of indirect references, is that in the future, very little changes would need to be made, if any, and your features would automatically get the new licenses included. Note that you need to use PDE Build from 37M5 or greater to use this function correctly.
 
+
  
 
==== Example of Tools output ====
 
==== Example of Tools output ====

Revision as of 05:43, 20 February 2011

Check and fix-up licenses tool

Updates ...

04/20/2010: Updated tool to use the new SUA document (new as of 4/2010!) as discussed in bug 306627.
04/24/2010: Updated tool to be more flexible in recognizing "license=" keys. bug 309988
02/20/2011: Updated tool to for new license (EUA) for Indigo and other 2011 releases (see bug 316152).
Added option to Migrate License Support for Indigo or releases based on 3.7 PDE Build (see bug 306818)

Introduction and background

This tool is a very simple aide to make license properties and files consistent in features[1]. In short, in addition to the Eclipse legal requirements of having the right SUAs, licenses, etc., beginning with the Helios release requirements, we want them to also be perfectly equivalent (same text, same case, same dates, etc.), when in fact they are the same. This is done to improve ease-of-use of the Installation UI and make the license acceptance more meaningful, since all features which have the same license can be grouped so users would have fewer of them to read.

This simple tool works on (only) workspace files. It finds all projects that are features, by looking for those that contain a "feature.xml" file. Then it looks for a "feature.properties" file. If found, it checks for a "license" property in that file, and compares its value with the value of the standard version. If different, it will update the feature.properties file with the new, consistent license text. It leaves other parts of the file untouched (such as, it leaves in existing comments and white space, and just replaces the license part.

If the tools finds it needs to update the 'license' property, then it will blindly add or replace an existing license.html file with the one that has the standard HTML content.

This tools was created to aide one specific case (Web Tools Platform), and is very much "unsupported", "use at your risk" sort of tool. That said ... it is hoped to be useful to others, so it is documented (here) and is available to all from the webtools releng repository.

How to use

To use the tool, first install it [2] and restart the Eclipse IDE.

Rewrite Licenses

To simply rewrite license files and properties, click Releng (on menu bar) and then click Rewrite Licenses. At that point, it does its work, modifying some if they are found inconsistent, but not others if already consistent, and it writes a log of what it finds and modifies in the workbench's console.

Before committing and releasing any modified files, be sure to compare and look closely the changes made, and made sure they are what is expected, and didn't mangle anything. That is, use at your own risk ... the ultimate responsibility is still yours, the tool is meant as only an aide utility, not necessarily a complete work-in-all-cases tool, since it should be needed to be used very seldom).

Migrate License Support

For Indigo, an additional menu command was added to aide in moving to the new type of license support, offered by PDE build. For Indigo, changes to builder was made to allow each feature to reference the license information indirectly, then it is retrieved and inserted in the right places at build time. See Kim Moir's excellent blog on the topic: Implementing shared licenses with 3.7M5.

This command makes the changes to feature projects that Kim outlines in her blog:

  • delete the files 'license.html' and 'epl-v10.html' if they exist. Correct/current one are added back at build time.
  • remove the references in build.properties to "export" the 'license.html' and 'epl-v10.html' files. (If present, a build

might fail if it does not find those files there, which were deleted).

  • remove the 'license' and 'licenseURL' properties in the features.properties in feature.properties (that are added back at build time).
  • Updates the feature.xml file so the feature element has two new attributes (in theory, the values could be difference, if you have your own custom standard license project to be used by your projects).
     license-feature="org.eclipse.license"
     license-feature-version="1.0.0.qualifier"

One change that is not made by the tool, that you have to make your self, is to add a line to one of your map files, that describes where to get your standard license feature and which version of it to get. For example, My guess it it will be common to use the same one used by the Eclipse Platform project:

  feature@org.eclipse.license=v20110208,:pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse,,org.eclipse.sdk-feature/features/org.eclipse.license


The advantages of using this new form of indirect references, is that in the future, very little changes would need to be made, if any, and your features would automatically get the new licenses included. Note that you need to use PDE Build from 37M5 or greater to use this function correctly.

Example of Tools output

Wtptool.png

Known limitations

  • Some data is hard code. For example, the license key must be, literally, 'license'. This is currently required by Eclipse installer, but in the general case there is no reason it has to be 'license'. If someone used something else, like 'licenseString' then the program would need to be modified (or, the key changed first, before using the tool). Similarly the actual license text and html file are 'hard coded' in the tools properties files. If they change in the future, or someone has their own special one, the tool would have to be changed. The source can be obtained from the Web Tools Platform repository in a webtools.releng module[3].
  • Property values for including 'license.html' and 'epl-v10.html' are removed only if they are on a line by themselves. This was done to "play it safe", (and use minimal programming effort), but can miss some important cases. The cases missed must be corrected "by hand", or can lead to a "missing file" build failure. In WTP, only about 3 cases were missed by this limitation (or more than 100 features), so doesn't seem too common (and not worth improving ... at least for WTP cases). [patches welcome :) ]
The following image shows a normal case, where the values are on a line by themselves, so are removed as intended.
NormalCleanup.png
The following image shows a case where 'license.html' is not modified, since on same line as "includes". Note also, the simple heuristic can leave a dangling continuation character at the end; This is valid from a Java Properties file syntax point of view, but usually not written that way be people.
LicenseMissed.png

References

  1. See bug 306627 for some history and details
  2. You can install "WTP Releng Tools Feature" from this repository.
    http://download.eclipse.org/webtools/releng/repository
  3. SCM CVS repository: fckLR:: :pserver:anonymous@dev.eclipse.org:/cvsroot/webtoolsfckLR: drill down directoryfckLR:: webtools.releng/plugins/fckLR: module: fckLR::org.eclipse.wtp.releng.fixups