ICU-6438 APIChangeReport should complain about things that break API change policy.

X-SVN-Rev: 24396
This commit is contained in:
Steven R. Loomis 2008-07-21 19:04:48 +00:00
parent fa50d4a3b2
commit 3d4773a197
9 changed files with 442 additions and 30 deletions

1
.gitattributes vendored
View File

@ -368,6 +368,7 @@ icu4j/src/com/ibm/icu/impl/duration/impl/data/pfd_zh_Hant.xml -text
icu4j/src/com/ibm/icu/impl/duration/impl/data/pfd_zh_Hant_HK.xml -text
icu4j/src/com/ibm/richtext/textapps/resources/unicode.arabic.red -text
icu4j/src/com/ibm/richtext/textapps/resources/unicode.hebrew.red -text
tools/release/java/icu4c.css -text
tools/unicodetools/com/ibm/rbm/docs/images/TitleLogo_transparent.gif -text
tools/unicodetools/com/ibm/rbm/docs/images/arrow_bullet.gif -text
tools/unicodetools/com/ibm/rbm/docs/images/diamond_bullet.gif -text

View File

@ -1,6 +1,12 @@
# Copyright (c) 2008 IBM and others. All Rights Reserved.
# api-report.properties contains properties for API report generation
#update these values to current version and directories
oldver=ICU 3.4
olddir=/work/clean/icu-3-4/source/doc/xml/
newver=ICU 3.6
newdir=/work/clean/icu-3-6/source/doc/xml/
## Version #'s are detected.
##oldver=ICU 3.8.1
olddir=/xsrl/E/icu4c381/source/doc/xml/
## Version #'s are detected.
##newver=ICU 4.0
#newdir=/xsrl/E/icu/source/doc/xml/
newdir=/xsrl/E/icu4ct/source/doc/xml/
#newdir=/xsrl/E/icu4cm40/source/doc/xml/

View File

@ -25,7 +25,7 @@
<condition property="is.sun.jdk14">
<and>
<equals arg1="${ant.java.version}" arg2="1.4"/>
<contains string="${java.vm.vendor}" substring="Sun Microsystems Inc"/>
<!--<contains string="${java.vm.vendor}" substring="Sun Microsystems Inc"/> -->
</and>
</condition>
<fail unless="is.sun.jdk14" message="Sun JDK1.4 is required."/>
@ -47,14 +47,20 @@
<target name="apireport" depends="tools">
<java classname="com.ibm.icu.dev.tools.docs.StableAPI" fork="yes" failonerror="true">
<arg value = "--oldver"/>
<!--
!! Only need these if you must override. Remove the DELETEME
<arg value = "-DELETEME-oldver"/>
<arg value = "${oldver}"/>
-->
<arg value = "--olddir"/>
<arg value = "${olddir}"/>
<arg value = "--newver"/>
<!--
!! Only need these if you must override. Remove the DELETEME
<arg value = "-DELETEME-newver"/>
<arg value = "${newver}"/>
-->
<arg value = "--newdir"/>
<arg value = "${newdir}"/>
@ -78,4 +84,4 @@
</classpath>
</java>
</target>
</project>
</project>

View File

@ -0,0 +1,245 @@
/*
* Default CSS style sheet for the ICU Open Source site
* Copyright (C) 2005-2008, International Business Machines
* Corporation and others. All Rights Reserved.
*/
/* Global styles */
body,p,li,ol,ul,th,td {
font-size: 10pt;
font-family: "Arial", "Helvetica", sans-serif;
}
body {
margin: 1em;
}
body.draft {
background-image: url(images/draftbg.png);
}
.mainbody {
padding: 1em;
}
/*
* Customize the headers to have less space around them than usual
*/
h1 {
margin-bottom: 5pt;
margin-top: 5pt;
font-weight: 700;
font-size: 20pt;
font-family: "Arial", "Helvetica", sans-serif;
}
h2 {
margin-bottom: 0pt;
margin-top: 12pt;
font-weight: 700;
font-size: 14pt;
font-family: "Arial", "Helvetica", sans-serif;
}
h3 {
background-color: #666666;
color: White;
margin-bottom: 0pt;
margin-top: 12pt;
padding-left: 0.75em;
font-size: 1em;
font-family: "Arial", "Helvetica", sans-serif;
}
h4 {
margin-bottom: 0pt;
margin-top: 12pt;
font-size: 1em;
font-family: "Arial", "Helvetica", sans-serif;
}
h5, h6 {
margin-bottom: 0pt;
margin-top: 12pt;
padding-left: 0.75em;
font-size: x-small;
font-family: "Arial", "Helvetica", sans-serif;
}
/*
* Navigation sidebar on the left hand of most pages
*/
td.sidebar1 {
background-color: #99CCFF;
font-weight: 700;
margin-top: 0px;
margin-bottom: 0px;
padding-top: 1em;
padding-left: 0.2em;
white-space: nowrap;
}
td.sidebar2 {
background-color: #99CCFF;
margin-top: 0px;
margin-bottom: 0px;
margin-left: 0px;
padding-top: 1px;
padding-bottom: 1px;
padding-left: 1px;
padding-right: 0.5em;
white-space: nowrap;
text-decoration: none;
display: block;
}
td.sidebar2:hover {
background-color: #EEEEFF;
padding-top: 1px;
padding-bottom: 1px;
padding-left: 1px;
padding-right: 0.5em;
}
a.sidebar2 {
text-decoration: none;
display: block;
width: 100%;
}
a.sidebar2:link {
color: #000099;
display: block;
}
a.sidebar2:hover {
background-color: #EEEEFF;
display: block;
}
.underlinehover:hover {
background-color: #EEEEFF;
text-decoration: underline;
}
/* This is the faded header at the top */
td.fadedtop {
background-color: #006699;
background-image: url(http://www.icu-project.org/images/gr100.gif);
}
/* Related site on the left */
p.relatedsite {
color: White;
font-weight: 700;
font-size: 10pt;
margin-top: 1em;
margin-bottom: 0;
padding-left: 0.2em;
white-space: nowrap;
}
/* Related site on the left */
p.sidebar3 {
margin-top: 0.75em;
margin-bottom: 0;
padding-left: 0.8em;
}
a.sidebar3 {
font-size: 0.9em;
text-decoration: none;
}
a.sidebar3:link {
text-decoration: none;
color: White;
}
a.sidebar3:hover {
text-decoration: underline;
}
/* FAQ */
li.faq_contents {
font-weight: 500;
}
p.faq_q {
font-weight: 700;
margin-bottom: 0px;
}
p.faq_a {
margin-top: 0px;
}
/* News items */
table.newsItem {
padding-left: 1em;
padding-right: 1em;
border-width: medium;
}
th.newsItem {
background-color: #666666;
color: White;
}
td.newsItem {
background-color: #CCCCCC;
}
td.release-line,th.release-line {
padding-left: 0.5em;
padding-right: 0.5em;
white-space: nowrap;
border:1px;
}
.note {
font-style: italic;
font-size: small;
margin-left: 1em;
}
samp {
margin-left: 1em;
margin-right: 2em;
border-style: groove;
padding: 1em;
display: block;
background-color: #EEEEEE
}
table.rtable caption {
margin-left: 2px;
margin-right: 2px;
padding: 3px;
font-weight: bold;
background-color: #dee2ff;
text-align: left;
}
table.rtable tr th {
background-color: #dee2ff;
text-align: left;
}
table.rtable tr td {
background-color: #c0c0fd;
padding: 3px;
}
/* APIChangeReport specific things */
.row0 {
background-color: white;
}
.row1 {
background-color: #dfd;
}
.verchange {
color: red;
font-weight: bold;
font-size: large;
}
.stabchange {
color: red;
font-size: large;
}
.bigwarn {
color: red;
background-color: white;
font-size: x-large;
margin: 0.5 em;
}

View File

@ -1,3 +1,4 @@
# Copyright (C) 2008 IBM and Others. All Rights Reserved
A tool to generate a report of API status changes between two ICU releases
@ -13,7 +14,7 @@ A tool to generate a report of API status changes between two ICU releases
c) gerenate the XML files
2. Build the tool
ant doctools
3. Edit the api-report.properties and change the values of oldver, olddir, newver, newdir
3. Edit the api-report.properties and change the values of olddir, newdir ( don't need to set oldver or newver)
4. Run the tool to generate the report
ant apireport

View File

@ -1,6 +1,6 @@
/*
**********************************************************************
* Copyright (c) 2006, International Business Machines
* Copyright (c) 2006-2008, International Business Machines
* Corporation and others. All Rights Reserved.
**********************************************************************
* Created on 2006-7-24
@ -80,15 +80,21 @@ public class StableAPI {
t.parseArgs(args);
Set full = new HashSet();
System.err.println("Reading C++...");
Set setCpp = t.getFullList(t.dumpCppXslt);
full.addAll(setCpp);
System.out.println("read "+setCpp.size() +" C++. Reading C:");
Set setC = t.getFullList(t.dumpCXslt);
full.addAll(setC);
System.out.println("read "+setC.size() +" C. Setting node:");
Node fullList = t.setToNode(full);
// t.dumpNode(fullList,"");
System.out.println("Node set. Reporting:");
t.reportSelectedFun(fullList);
System.out.println("Done. Please check " + t.resultFile);
}
@ -123,6 +129,100 @@ public class StableAPI {
printUsage();
}
}
leftVer = trimICU(setVer(leftVer, "old", leftDir));
rightVer = trimICU(setVer(rightVer, "new", rightDir));
}
private static String trimICU(String ver) {
final String ICU_ = "ICU ";
final String ICU = "ICU";
if(ver != null) { // trim everything before the 'ICU...'
ver = ver.trim();
int icuidx = ver.lastIndexOf(ICU_);
int icuidx1 = ver.lastIndexOf(ICU);
if(icuidx>=0) {
ver = ver.substring(icuidx+ICU_.length()).trim();
} else if(icuidx1>=0) {
System.err.println("Warning: SuperTrimming: '" + ver + "'");
ver = ver.substring(icuidx1+ICU.length()).trim();
} else {
int n;
for(n=ver.length()-1;n>0 && ((ver.charAt(n)=='.') || Character.isDigit(ver.charAt(n))) ;n--)
;
System.err.println("Warning: SuperDuperTrimming: '" + ver + "'");
if(n>0) {
ver = ver.substring(n+1).trim();
}
}
}
return ver;
}
private String setVer(String prevVer, String whichVer, String dir) {
final String UVERSION = "uversion_8h.xml";
String result = null;
// looking for: <name>U_ICU_VERSION</name> in uversion_8h.xml: <initializer>&quot;3.8.1&quot;</initializer>
try {
Document doc = getDocument(dir + UVERSION);
DOMSource uversion_h = new DOMSource(doc);
Node defines = XPathAPI.selectSingleNode(uversion_h.getNode(),"/doxygen/compounddef[@id='uversion_8h'][@kind='file']/sectiondef[@kind='define']");
NodeList nList = defines.getChildNodes();
for (int i = 0; result==null&& (i < nList.getLength()); i++) {
Node ln = nList.item(i);
if(!"memberdef".equals(ln.getNodeName())) {
continue;
}
Node name = XPathAPI.selectSingleNode(ln, "name");
if(name==null) continue;
// System.err.println("Gotta node: " + name);
Node nameVal = name.getFirstChild();
if(nameVal==null) nameVal = name;
String nameStr = nameVal.getNodeValue();
if(nameStr==null) continue;
// System.err.println("Gotta name: " + nameStr);
if(nameStr.trim().equals("U_ICU_VERSION")) {
Node initializer = XPathAPI.selectSingleNode(ln, "initializer");
if(initializer==null) System.err.println("initializer with no value");
Node initVal = initializer.getFirstChild();
// if(initVal==null) initVal = initializer;
String initStr = initVal.getNodeValue().trim().replaceAll("\"","");
result = "ICU "+initStr;
System.err.println("Detected "+whichVer + " version: " + result);
}
}
//dumpNode(defines,"");
} catch(Throwable t) {
t.printStackTrace();
System.err.println("Warning: Couldn't get " + whichVer+ " version from "+ UVERSION + " - reverting to " + prevVer);
result = prevVer;
}
if(prevVer != null) {
if(result != null) {
if(!result.equals(prevVer)) {
System.err.println("Note: Detected " + result + " version but we'll use your requested --"+whichVer+"ver "+prevVer);
result = prevVer;
} else {
System.err.println("Note: You don't need to use '--"+whichVer+"ver "+result+"' anymore - we detected it correctly.");
}
}
}
if(result == null) {
System.err.println("Error: You'll need to use the option \"--"+whichVer+"ver\" because we could not detect an ICU version in " + UVERSION );
throw new InternalError("Error: You'll need to use the option \"--"+whichVer+"ver\" because we could not detect an ICU version in " + UVERSION );
}
return result;
}
private static void printUsage(){
@ -130,9 +230,9 @@ public class StableAPI {
System.out.println();
System.out.println("Options:");
System.out.println(" --help Print this text");
System.out.println(" --oldver Version of old version of ICU");
System.out.println(" --oldver Version of old version of ICU (optional)");
System.out.println(" --olddir Directory that contains xml docs of old version");
System.out.println(" --newver Version of new version of ICU");
System.out.println(" --newver Version of new version of ICU (optional)");
System.out.println(" --newdir Directory that contains xml docs of new version");
System.out.println(" --cxslt XSLT file for C docs");
System.out.println(" --cppxslt XSLT file for C++ docs");
@ -153,6 +253,7 @@ public class StableAPI {
public String prototype;
public String id;
public String status;
public String version;
public String file;
public boolean equals(Fun right){
return this.prototype.equals(right.prototype);
@ -162,6 +263,7 @@ public class StableAPI {
f.prototype = getAttr(n, "prototype");
f.id = getAttr(n, "id");
f.status = getAttr(n, "status");
f.version = trimICU(getAttr(n, "version"));
f.file = getAttr(n, "file");
f.purifyPrototype();
f.purifyFile();
@ -203,6 +305,8 @@ public class StableAPI {
public String prototype;
public String leftRefId;
public String leftStatus;
public String leftVersion;
public String rightVersion;
public String leftFile;
public String rightRefId;
public String rightStatus;
@ -215,6 +319,8 @@ public class StableAPI {
u.leftStatus = left.status;
u.leftFile = left.file;
u.rightRefId = nul;
// u.rightVersion = nul;
u.leftVersion = left.version;
u.rightStatus = nul;
u.rightFile = nul;
return u;
@ -226,6 +332,8 @@ public class StableAPI {
u.leftRefId = nul;
u.leftStatus = nul;
u.leftFile = nul;
// u.leftVersion = nul;
u.rightVersion = right.version;
u.rightRefId = right.id;
u.rightStatus = right.status;
u.rightFile = right.file;
@ -241,6 +349,8 @@ public class StableAPI {
u.leftFile = left.file;
u.rightRefId = right.id;
u.rightStatus = right.status;
u.leftVersion = left.version;
u.rightVersion = right.version;
u.rightFile = right.file;
return u;
}
@ -253,6 +363,9 @@ public class StableAPI {
ele.setAttribute("leftStatus", leftStatus);
// ele.setAttribute("rightRefId", rightRefId);
ele.setAttribute("rightStatus", rightStatus);
ele.setAttribute("leftVersion", leftVersion);
// ele.setAttribute("rightRefId", rightRefId);
ele.setAttribute("rightVersion", rightVersion);
// String f = rightRefId.equals(nul) ? leftRefId : rightRefId;
@ -272,6 +385,7 @@ public class StableAPI {
// report.setParameter("leftStatus", leftStatus);
report.setParameter("leftVer", leftVer);
// report.setParameter("rightStatus", rightStatus);
report.setParameter("ourYear", new Integer(new java.util.GregorianCalendar().get(java.util.Calendar.YEAR)));
report.setParameter("rightVer", rightVer);
report.setParameter("dateTime", new GregorianCalendar().getTime());
report.setParameter("nul", nul);

View File

@ -1,14 +1,14 @@
<!--
/*
*******************************************************************************
* Copyright (C) 2006, International Business Machines Corporation and *
* Copyright (C) 2008, International Business Machines Corporation and *
* others. All Rights Reserved. *
*******************************************************************************
* This is the ant build file for ICU tools.
* This is an XSLT build file for ICU tools.
*/
-->
<!--
List all c functions generated from the 'index.xml'
List all C functions generated from the 'index.xml'
-->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:param name="docFolder" />
@ -23,6 +23,7 @@
<cppfunc>
<xsl:copy-of select="@id" />
<xsl:attribute name="status"><xsl:value-of select="detaileddescription/para/xrefsect/xreftitle/text()"/></xsl:attribute>
<xsl:attribute name="version"><xsl:value-of select="detaileddescription/para/xrefsect/xrefdescription/para/text()"/></xsl:attribute>
<xsl:attribute name="prototype"><xsl:value-of select="concat(definition/text(), argsstring/text())" /></xsl:attribute>
<xsl:copy-of select="location/@file" />
</cppfunc>

View File

@ -1,14 +1,14 @@
<!--
/*
*******************************************************************************
* Copyright (C) 2006, International Business Machines Corporation and *
* Copyright (C) 2008, International Business Machines Corporation and *
* others. All Rights Reserved. *
*******************************************************************************
* This is the ant build file for ICU tools.
* This is an XSLT file.
*/
-->
<!--
List all cpp pulbic functions generated from the 'index.xml'
List all cpp public functions generated from the 'index.xml'
-->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:param name="docFolder" />
@ -23,6 +23,7 @@
<cppfunc>
<xsl:copy-of select="@id" />
<xsl:attribute name="status"><xsl:value-of select="detaileddescription/para/xrefsect/xreftitle/text()"/></xsl:attribute>
<xsl:attribute name="version"><xsl:value-of select="detaileddescription/para/xrefsect/xrefdescription/para/text()"/></xsl:attribute>
<xsl:attribute name="prototype"><xsl:value-of select="concat(definition/text(), argsstring/text())" /></xsl:attribute>
<xsl:copy-of select="location/@file" />
</cppfunc>

View File

@ -1,10 +1,10 @@
<!--
/*
*******************************************************************************
* Copyright (C) 2006, International Business Machines Corporation and *
* Copyright (C) 2008, International Business Machines Corporation and *
* others. All Rights Reserved. *
*******************************************************************************
* This is the ant build file for ICU tools.
* This is the XSLT for the API Report.
*/
-->
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
@ -16,12 +16,16 @@
<xsl:param name="rightVer" />
<xsl:param name="dateTime" />
<xsl:param name="nul" />
<xsl:param name="ourYear" />
<xsl:template match="/">
<!-- Copyright (C) 2008, International Business Machines Corporation, All Rights Reserved. -->
<html>
<head>
<title>ICU4C API Comparison: <xsl:value-of select="$leftVer"/> with <xsl:value-of select="$rightVer" /> </title>
<link rel="stylesheet" href="icu4c.css" type="text/css" />
</head>
<body>
@ -43,7 +47,7 @@
<h2>Changed in <xsl:value-of select="$rightVer" /> (old, new)</h2>
<xsl:call-template name="genTable">
<xsl:with-param name="nodes" select="/list/func[(@leftStatus != $nul) and (@rightStatus != $nul) and (@leftStatus != @rightStatus)]"/>
<xsl:with-param name="nodes" select="/list/func[(@leftStatus != $nul) and (@rightStatus != $nul) and ( (@leftStatus != @rightStatus) or (@leftVersion != @rightVersion) )]"/>
</xsl:call-template>
<P/><hr/>
@ -62,7 +66,7 @@
-->
<p><i><font size="-1">Contents generated by StableAPI tool on <xsl:value-of select="$dateTime" /><br/>Copyright (C) 2006, International Business Machines Corporation, All Rights Reserved.</font></i></p>
<p><i><font size="-1">Contents generated by StableAPI tool on <xsl:value-of select="$dateTime" /><br/>Copyright (C) <xsl:value-of select="$ourYear" />, International Business Machines Corporation, All Rights Reserved.</font></i></p>
</body>
</html>
</xsl:template>
@ -73,7 +77,7 @@
<THEAD>
<tr>
<th> <xsl:value-of select="'File'" /> </th>
<th> <xsl:value-of select="'Public API Prototype'" /> </th>
<th> <xsl:value-of select="'API'" /> </th>
<th> <xsl:value-of select="$leftVer" /> </th>
<th> <xsl:value-of select="$rightVer" /> </th>
</tr>
@ -81,16 +85,49 @@
<xsl:for-each select="$nodes">
<xsl:sort select="@file" />
<tr>
<xsl:attribute name="STYLE">
<xsl:if test ="@leftStatus = 'Stable'">
<xsl:value-of select="'color: red'" />
</xsl:if>
<xsl:attribute name="class">
<xsl:value-of select="'row'"/>
<xsl:value-of select="(position() mod 2)"/>
<!--
<xsl:choose>
<xsl:when test="(position() mod 2) = 0"><xsl:value-of select="row0" /></xsl:when>
<xsl:otherwise><xsl:value-of select="row1" /></xsl:otherwise>
</xsl:choose>
-->
</xsl:attribute>
<td> <xsl:value-of select="@file" /> </td>
<td> <xsl:value-of select="@prototype" /> </td>
<td> <xsl:value-of select="@leftStatus" /> </td>
<td> <xsl:value-of select="@rightStatus" /> </td>
<td>
<xsl:attribute name="class">
<xsl:if test ="@leftStatus = 'Stable'">
<xsl:value-of select="'stabchange'" />
</xsl:if>
</xsl:attribute>
<xsl:value-of select="@leftStatus" />
<br/> <xsl:value-of select="@leftVersion" />
</td>
<td> <xsl:value-of select="@rightStatus" />
<br/>
<span>
<xsl:attribute name="class">
<xsl:if test ="@leftVersion != @rightVersion and @leftVersion != '' and @rightVersion != ''">
<xsl:value-of select="'verchange'" />
</xsl:if>
</xsl:attribute>
<span>
<xsl:value-of select="@rightVersion" />
</span>
<xsl:if test ="@leftVersion != @rightVersion and @leftVersion != '' and @rightVersion != '' and @rightStatus = 'Stable'">
<br/><b title='A stable API changed version.' class='bigwarn'>(changed)</b>
</xsl:if>
<xsl:if test ="@rightStatus = 'Draft' and @rightVersion != $rightVer">
<br/><b title='A draft API has the wrong version.' class='bigwarn'>(should be <xsl:value-of select="$rightVer"/>)</b>
</xsl:if>
</span>
</td>
</tr>
</xsl:for-each>
</table>