::::Added option to <code>Migrate License Support</code> for Indigo or other releases based on 3.7 PDE Build (see {{bug|306818}})

=== Introduction and background ===

=== Introduction and background ===

Line 21:

Line 21:

=== How to use ===

=== How to use ===

−

To use the tool, first install it <ref>You can install "WTP Releng Tools Feature" from this repository.

+

To use the tool, first install it <ref>You can install "WTP Releng Tools Fixup Feature" from this repository.

: http://download.eclipse.org/webtools/releng/repository </ref> and restart the Eclipse IDE. Then you'll see a new item on the menu bar, <code>Releng</code> with two sub-items: <code>Rewrite Licenses</code> and <code>Migrate License Support</code>.

: http://download.eclipse.org/webtools/releng/repository </ref> and restart the Eclipse IDE. Then you'll see a new item on the menu bar, <code>Releng</code> with two sub-items: <code>Rewrite Licenses</code> and <code>Migrate License Support</code>.

Line 36:

Line 36:

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

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.

+

* delete the files 'license.html' and 'epl-v10.html' if they exist. The correct or current ones are added 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 references in build.properties to "include" the 'license.html' and 'epl-v10.html' files. Proof read carefully. The tool does not catch all cases, and if present in an 'includes' property, a build will 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).

+

* remove the 'license' and 'licenseURL' properties in the features.properties in feature.properties (they are added back at build time, so are in final, built version ... just not the cvs version).

−

* 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).

+

* Updates the feature.xml file so the feature element has two new attributes (in theory, the values you need could be different, if you have your own custom standard license project to be used by your projects ... but, for now is hard coded in tool).

license-feature="org.eclipse.license"

license-feature="org.eclipse.license"

license-feature-version="1.0.0.qualifier"

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. Take the following as an example only, but my guess is it will be common practice to use the same license-feature used by the Eclipse Platform project:

+

One change that is needed, but that is not made by the tool, is to add a line to one of the map files, that describes where to get the standard license feature and exactly which version of it to get. Take the following as an example only, but my guess is it will be common practice to use the same license-feature used by the Eclipse Platform project:

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 license included. Note that you need to use PDE Build from 37M5 or greater to use this function correctly. Some reasons to not use this type of support (and use <code>Rewrite Licenses</code> instead) is if your build system does not use PDE's feature build (I've heard they all do, at their cores) or, if for some reason, you can not move to an 37M5 based builder.

+

The advantages of using this new form of indirect license-by-reference support, is that in the future, very few, if any, changes would be needed to pick up the new license during a rebuild. Note that you need to use PDE Build from 37M5 or greater to use this function correctly. Some reasons to not use this type of support (and use <code>Rewrite Licenses</code> instead) is if your build system does not use PDE's feature build (I've heard they all do, at their cores) or, if for some reason, you can not move to an 37M5 based builder.

==== Example of Tools output ====

==== Example of Tools output ====

Line 57:

Line 57:

=== Known limitations ===

=== 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<ref>SCM CVS repository:<br /><nowiki>

+

*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<ref>SCM CVS repository:<br />

*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&nbsp;:) ]

+

*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 (of more than 100 features), so doesn't seem too common (and not worth improving ... at least for WTP cases). [patches welcome&nbsp;:) ]

:The following image shows a normal case, where the values are on a line by themselves, so are removed as intended.

:The following image shows a normal case, where the values are on a line by themselves, so are removed as intended.

Line 70:

Line 70:

:[[Image:NormalCleanup.png]]<br>

:[[Image:NormalCleanup.png]]<br>

−

: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.

+

: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 by people.

Use standard licenses in features

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 for new license (SUA) for Indigo and other 2011 releases (see bug 316152).

Added option to Migrate License Support for Indigo or other 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. Then you'll see a new item on the menu bar, Releng with two sub-items: Rewrite Licenses and Migrate License Support.

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. The correct or current ones are added at build time.

remove the references in build.properties to "include" the 'license.html' and 'epl-v10.html' files. Proof read carefully. The tool does not catch all cases, and if present in an 'includes' property, a build will 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 (they are added back at build time, so are in final, built version ... just not the cvs version).

Updates the feature.xml file so the feature element has two new attributes (in theory, the values you need could be different, if you have your own custom standard license project to be used by your projects ... but, for now is hard coded in tool).

One change that is needed, but that is not made by the tool, is to add a line to one of the map files, that describes where to get the standard license feature and exactly which version of it to get. Take the following as an example only, but my guess is it will be common practice to use the same license-feature used by the Eclipse Platform project:

The advantages of using this new form of indirect license-by-reference support, is that in the future, very few, if any, changes would be needed to pick up the new license during a rebuild. Note that you need to use PDE Build from 37M5 or greater to use this function correctly. Some reasons to not use this type of support (and use Rewrite Licenses instead) is if your build system does not use PDE's feature build (I've heard they all do, at their cores) or, if for some reason, you can not move to an 37M5 based builder.

Example of Tools output

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 (of 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.

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 by people.