[Clirr-devel] CVS: clirr/core/src/site/xdoc exegesis.xml, NONE, 1.1 anttask.xml, NONE, 1.1 runcli.x
Status: Alpha
Brought to you by:
lkuehne
Menu
▾
▴
[Clirr-devel] CVS: clirr/core/src/site/xdoc exegesis.xml, NONE, 1.1 anttask.xml, NONE, 1.1 runcli.xml, NONE, 1.1 index.xml, NONE, 1.1
|
From: Lars K. <lk...@us...> - 2008-10-06 22:08:30
|
Update of /cvsroot/clirr/clirr/core/src/site/xdoc In directory ddv4jf1.ch3.sourceforge.com:/tmp/cvs-serv24670/src/site/xdoc Added Files: exegesis.xml anttask.xml runcli.xml index.xml Log Message: moved site sources to correct location for maven2 site plugin --- NEW FILE --- <?xml version="1.0" encoding="ISO-8859-1"?> <document> <properties> <title>Difference Message Reference Manual</title> <author>The Clirr Development Team</author> </properties> <body> <section name="Introduction"> <p> When clirr generates an ERROR, WARNING or INFO message about a change in the jars being compared, there is an associated message reference code. This document contains an explanation of the meaning of that message which may contain information which could not be fitted into the brief message summary. </p> <p> Messages are separated into three severity levels: <ul> <li>ERROR</li> <li>WARNING</li> <li>INFO</li> </ul> </p> <p> Errors come in two flavours: <ul> <li> Link-time failures, where an exception will be thrown as soon as code compiled against an old version of a class and the new version of the class are loaded into the same classloader hierarchy. </li> <li> Run-time failures, where an exception is thrown when code compiled against the old version of a class attempts to call a method on a new version of the class, or vice versa. </li> </ul> <p> Clirr reports "errors" for cases where it is <i>possible</i> to get a run-time failure. Whether one actually occurs can depend upon the way the library is called, ie changes reported as an error may in fact work when used as long as the patterns of use of the library do not trigger the failure situation. </p> </p> <p> Warnings are issued for situations where no link or runtime exception will occur, but where the application may behave unexpectedly due to the changes that have occurred. </p> <p> Information messages provide users with information about new features which have been added without breaking backward compatibility in any way. </p> <p> When using clirr to report on changes to items which have private or package scope, these changes are always reported as INFO level changes, never WARNING or ERROR level. This allows users of clirr to generate "change reports" at a level suitable for developers without having some of those changes marked (irrelevantly) as binary incompatibilities. </p> <p> There can never be binary incompatibilities for changes to private classes, methods or fields as that access can only occur from within the same class (ie the same compilation unit). </p> <p> Clirr does not report binary incompatibility WARNINGs or ERRORs for package-scoped items either, because java packages are intended to be "release units", ie all classes within a package are compiled together (ensuring compatibility) then released as a unit. The only time that package-scope incompatibilities could possibly be an issue is when users of a library write their own classes using a package declaration belonging to some external library, or when a subset of updated classes (eg a single class) from a package is used to override certain classes from a previous release of the library. Both of these situations are considered very poor practice by java programming convention. </p> <p> In the following sections, the term "old" is used to refer to a class, interface, method or field from the set of jars which represent the old/previous/original/baseline version of the library being inspected. The term "new" is used to refer to a class, interface, method or field from the set of jars which represent the new/current/latest version of the library being inspected. </p> <p> In the following sections, the term "type" is used to refer to something which may be either a class or interface. </p> </section> <section name="Messages"> <section name="1000 - Increased visibility of class"> <p>Severity: <code>INFO</code></p> <p> The specified type exists in both versions, but its declared access specifier has changed to relax restrictions on what other code can access it. </p> <p> Top-level types (ie those which are not nested within another class) may only have "package" or "public" accessibility. Nested types can take on any of the four available accessibility values. </p> <p> Regardless of whether the object is top-level or nested, a change in accessibility from left-to-right of the sequence private->package->protected->public always ensures that all code which could previously access that type can still access that type. Therefore such a change is always binary and source-code compatible. </p> <p> Note that the declaration "protected" provides access to <i>both</i> code derived from the type <i>and</i> to code within the same package, ie "protected" accessibility also implies package accessibility. </p> </section> <section name="1001 - Decreased visibility of class"> <p>Severity: <code>ERROR</code></p> <p> The specified type exists in both versions, but its declared access specifier has changed to tighten the restrictions on what other code may access it. </p> <p> Top-level types (ie those which are not nested within another class) may only have "package" or "public" accessibility. Nested types can take on any of the four available accessibility values. </p> <p> Regardless of whether the type is top-level or nested, a change in accessibility from left-to-right of the sequence public->protected->package->private may cause existing code which could previously access the type to no longer be able to do so. </p> <p> Section 13.4.3 of the java language specification states explicitly that an IllegalAccessError should occur if a pre-existing binary tries to access a type when the type accessibility has been changed to something that would cause a compile-time error. However this does not appear to be enforced in practice, at least in current JVMs. Nevertheless this <i>should</i> be an error, and so clirr reports this change as a binary-compatibility ERROR. </p> </section> <section name="2000 - Changed from class to interface"> <p>Severity: <code>ERROR</code></p> <p> The specified class has become an interface in the new version. This change is always a binary and source-code incompatibility, for obvious reasons. </p> </section> <section name="2001 - Changed from interface to class"> <p>Severity: <code>ERROR</code></p> <p> The specified interface has become an class in the new version. This change is always a binary and source-code incompatibility, for obvious reasons. </p> </section> <section name="3001 - Removed final modifier from class"> <p>Severity: <code>INFO</code></p> <p> The specified class was declared final in the old version, but is no longer final in the new version. </p> </section> <section name="3002 - Added final modifier to effectively final class"> <p>Severity: <code>INFO</code></p> <p> The specified class was not declared final in the old version, but is now declared final. Normally, this would be an incompatibility because pre-existing derived classes would no longer be valid when used with the new version of this class. However in this case the old class version had no public or protected constructors, so it was not possible for any derived classes to exist even for the old version of the library. Changing such a class to final therefore can not break any existing code. </p> </section> <section name="3003 - Added final modifier to class"> <p>Severity: <code>ERROR</code></p> <p> The specified class was not declared final in the old version, but is now declared final. Any pre-existing classes which were declared as subclasses of this class will therefore not be valid with the new version of the library. </p> <p> A VerifyError is thrown by the classloader when an attempt is made to load a subclass of a final class. </p> <p> Note that a class Y is loaded by the standard classloader only when the first attempt is made to create an instance of Y, or to directly reference the Class object for class Y. If some other class X has class Y as a declared member, or as a parameter to some method, then loading class X does <em>not</em> cause class Y to be loaded. </p> </section> <section name="3004 - Removed abstract modifier from class"> <p>Severity: <code>INFO</code></p> <p> The old version of this class was declared to be an abstract class. The new version is not abstract, allowing users to create instances of the class. </p> </section> <section name="3005 - Added abstract modifier to class"> <p>Severity: <code>ERROR</code></p> <p> The old version of this class was not declared to be abstract. The new version is abstract. Pre-existing code which creates instances of this class is no longer valid with the new version. </p> </section> <section name="4000 - Added interface to the set of implemented interfaces"> <p>Severity: <code>INFO</code></p> <p> The new version of the type now implements an additional interface. This does not invalidate any existing code (source or binary), and is a completely backward-compatible change. </p> <p> Note that this message can be reported without any change occurring in the specified type; a change to the set of interfaces supported by a type will cause this message to be reported for every descendant of that type. </p> </section> <section name="4001 - Removed interface from the set of implemented interfaces"> <p>Severity: <code>ERROR</code></p> <p> The old version of this type declared that it implemented an interface which the new class or interface does not. Existing code which explicitly or implicitly casts objects of this type to the now missing interface is no longer valid. </p> <p> Note that this message can be reported without any change occurring in the specified type; a change to the set of interfaces supported by a type will cause this message to be reported for every descendant of that type. </p> </section> <section name="5000 - Added class to the set of superclasses"> <p>Severity: <code>INFO or WARNING</code></p> <p> The new version of the class has a class in its inheritance hierarchy which the old version did not, either because its direct parent is now a different class, or because one of its parent classes has changed its inheritance hierarchy. </p> <p> If the specified class has java.lang.Throwable as an ancestor, then this change is reported as a WARNING, because this class change may change the exception-catching behaviour of programs that use this class. </p> <p> Note that this message can be reported without any change occurring in the specified class; a change to the set of superclasses of an ancestor class will cause this message to be reported for every descendant class. </p> </section> <section name="5001 - Removed class from the set of superclasses"> <p>Severity: <code>ERROR</code></p> <p> The old version of this class has a class in its inheritance hierarchy which the new version does not, either because its direct parent is now a different class, or because one of its parent classes has changed its inheritance hierarchy. </p> <p> Existing code which explicitly or implicitly casts objects of this type to the now missing class type is no longer valid. </p> <p> Note that this message can be reported without any change occurring in the specified class; a change to the set of superclasses of an ancestor class will cause this message to be reported for every descendent class. </p> <p> Note also that if this class has Throwable in its ancestry, then the class hierarchy change can also cause changes in the exception-catching behaviour of programs using this class. </p> </section> <section name="6000 - Added field"> <p>Severity: <code>INFO</code></p> <p> The new class has an additional static or instance member. This change is completely backwards-compatible. </p> </section> <section name="6001 - Removed field"> <p>Severity: <code>ERROR</code></p> <p> The new class has removed a field present in the old version. Pre-existing code which directly accesses that field will no longer be valid. </p> </section> <section name="6002 - Value of field no longer a compile-time constant"> <p>Severity: <code>WARNING</code></p> <p> Code compiled against the old version of the class was permitted to "inline" the value of this field because it was a compile-time constant. Therefore, existing binary code will continue to use the old value of this field, instead of the new value (which cannot be inlined). </p> </section> <section name="6003 - Value of compile-time constant has changed"> <p>Severity: <code>WARNING</code></p> <p> Code compiled against the old version of the class was permitted to "inline" the value of this field because it was a compile-time constant. Therefore, existing binary code will continue to use the old value of this field, instead of the new value. </p> </section> <section name="6004 - Field type changed"> <p>Severity: <code>ERROR</code></p> <p> The type associated with the specified static or instance member of the specified class has changed. Pre-existing code which directly accesses that field may no longer be valid, and therefore this is an incompatible change. </p> </section> <section name="6005 - Field now non-final"> <p>Severity: <code>INFO</code></p> <p> The field was previously final, and is no longer final. This means that the field value can now be modified during the lifetime of the class or instance. </p> <p> Whether a value in a field could previously be "inlined" into other classes is an issue addressed by messages 6002 and 6003, not this message. </p> </section> <section name="6006 - Field now final"> <p>Severity: <code>ERROR</code></p> <p> The field can no longer be modified during the lifetime of the class or instance. Code which previously modified this field is therefore no longer valid. </p> </section> <section name="6007 - Field now non-static"> <p>Severity: <code>ERROR</code></p> <p> The field is now an instance variable rather than a class variable. Code which previously accessed this field via the Class rather than an instance of the class is no longer valid. </p> </section> <section name="6008 - Field now static"> <p>Severity: <code>ERROR</code></p> <p> The field is now a class variable rather than an instance variable. </p> <p> For some reason (presumably internal implementation issues), the java standard declares that this change is not binary-compatible, and that an IncompatibleClassChangeError will be thrown if code compiled against the "old" version of a class is used together with a "new" version for which a field is now static. </p> <p> Because source code is permitted to access class variables via instances of that class, this is expected to be a source-code compatible change. However currently CLIRR reports this as an ERROR for source-code compatibility too. </p> </section> <section name="6009 - Field More Accessible"> <p>Severity: <code>INFO</code></p> <p> In the new version, the specified field is accessible to more code than it was previously. </p> </section> <section name="6010 - Field Less Accessible"> <p>Severity: <code>ERROR</code></p> <p> In the new version, the specified field is accessible to less code than it was previously. Therefore existing code may no longer be valid. </p> </section> <section name="6011 - Removed Constant Field"> <p>Binary Severity: <code>WARNING</code></p> <p>Source Severity: <code>ERROR</code></p> <p> The new class has removed a field present in the old version. Pre-existing source code which directly accesses that field will no longer be valid. </p> <p> Previously, however, the field was final and was initialised with a constant value. Therefore code compiled against the previous version of the class will have inlined this constant and will continue to work, using the previous value of this field. A warning is issued as this is often not desirable behaviour. However it is not a binary incompatibility. </p> </section> <section name="7000 - Method now in Superclass"> <p>Severity: <code>INFO</code></p> <p> The old class had a method named X. The new class no longer has this method, but a parent class does define this method, so no binary or source incompatibility has occurred. </p> <p> Note that this change may have the effect of forcing the new class to become 'abstract'. If this is the case, then this change is reported separately. </p> </section> <section name="7001 - Method now in Interface"> <p>Severity: <code>INFO</code></p> <p> The old class or interface previously had a method named X. The new class or interface no longer has this method, but a parent interface does define this method, so no binary or source incompatibility has occurred. </p> <p> Note that this change may have the effect of forcing the new class to become 'abstract'. If this is the case, then this change is reported separately. </p> </section> <section name="7002 - Method Removed"> <p>Severity: <code>ERROR</code></p> <p> The old class or interface had a method named X. The new class or interface no longer has this method, and this method is not defined on any parent class or interface. </p> <p> Whether an error actually occurs at runtime for this change depends on usage patterns. The modified class can be used with existing code as long as that existing code does not attempt to call the removed method. If a call to the missing method is made, then a NoSuchMethodError exception is generated when the method invocation occurs. </p> </section> <section name="7003 - Method Overide Removed"> <p>Severity: <code>INFO</code></p> <p> The specified method on the old class or interface was overriding an inherited definition. The new class or interface no longer has this method explicitly declared on it, but it still inherits a definition so there is no binary incompatibility. </p> </section> <section name="7004 - Method Argument Count Changed"> <p>Severity: <code>ERROR</code></p> <p> The specified method has had arguments added or removed. This means that code which previously invoked it will no longer invoke the same method. </p> <p> If there is an inherited method definition with the old prototype, then there is no binary incompatibility; code which was compiled against the old version of this class will now invoke the inherited implementation. <em>In this situation, clirr should output an INFO message rather than an error. However at the current date, clirr does not check for this situation</em>. </p> <p> If there is no inherited method definition with the old prototype, then the change is a binary incompatibility. </p> </section> <section name="7005 - Method Argument Type changed"> <p>Binary Severity: <code>INFO or ERROR</code></p> <p>Source Severity: <code>ERROR</code></p> <p> The specified method has had the type of one or more of its arguments modified. This means that code compiled against the old version of the class will no longer invoke the same method. However exactly the same old source code, when compiled against the new class version <i>may</i> invoke this method if the argument types are assignment-compatible. </p> <p> If there is an inherited method definition with the old prototype, then there is no binary incompatibility; code which was compiled against the old version of this class will now invoke the inherited implementation. <em>At the current date, clirr does not check for this situation</em>. </p> <p> If there is no inherited method definition with the old prototype, then the change is a binary incompatibility. </p> <p> If the parameter types changed were all changed to <i>supertypes</i> of their previous declared types, or for primitive parameter types if they were changed to "larger" types in every case, then the new code is <i>source-code-compatible</i> with the previous release even if it is not binary-compatible. Note that in this situation, recompiling code which uses the library may change its behaviour from calling an inherited method to calling a method on the class which has a slightly different prototype. <em>At the current date, clirr does not check for this situation</em>. </p> </section> <section name="7006 - Method Return Type changed"> <p>Binary Severity: <code>ERROR</code></p> <p>Source Severity: <code>INFO or ERROR</code></p> <p> The specified method has had its declared return type changed. Whether a problem actually occurs at runtime when using code compiled against the old version of this library depends upon usage patterns. Old code may call other methods on this class. However any attempt to call the method whose return type has changed will result in a NoSuchMethodError being thrown when the method is invoked, because the return type is part of the "method signature". </p> <p> The change is <i>source-code-compatible</i> if and only if the new return type is <i>assignable to</i> the old return type. This means that: <ul> <li> if the old return type was a primitive type, then the new return type must be <i>narrower</i> than the old type. </li> <li> if the old return type was an interface, then the new return type must be a class or interface which implements the old return type. </li> <li> if the old return type was a class, then the new return type must be a subclass of the previously returned type. </li> </ul> Clirr does not currently check for source-code compatibility for changes in method return types; currently these are simply reported as an ERROR. </p> </section> <section name="7007 - Method has been Deprecated"> <p>Severity: <code>INFO</code></p> <p> The specified method has been declared as "deprecated". This is always a binary-compatible change as well as a source-code-compatible change. </p> </section> <section name="7008 - Method has been Undeprecated"> <p>Severity: <code>INFO</code></p> <p> The specified method was declared "deprecated" in the previous version, but is no longer deprecated in the current release. While slightly unusual, this is permitted. This change is always a binary-compatible change as well as a source-code-compatible change. </p> </section> <section name="7009 - Method is now Less Accessible"> <p>Severity: <code>ERROR</code></p> <p> The access permissions associated with the specified method have been tightened to permit less user code to access the method. </p> <p> Whether this change is a source-code compatibility issue or not depends upon patterns of usage. </p> <p> This change <i>should</i> be a binary incompatibility. Note, however, that current JVMs do not validate this. Code compiled against a previous version of a class can successfully invoke methods for which they no longer have access rights. Nevertheless, the java language specification states that this is an error, so clirr reports this change as a binary incompatibility. </p> </section> <section name="7010 - Method is now More Accessible"> <p>Severity: <code>INFO</code></p> <p> The access permissions associated with the specified method have been loosened to permit more user code to access the method. This is always a binary and source-code compatible change. </p> </section> <section name="7011 - Method Added"> <p>Severity: <code>INFO</code></p> <p> A non-abstract method has been added to the specified class. This is always a binary-compatible change. </p> <p> It is also a source-code compatible change. </p> <p> Q: if the new method overrides an inherited one, then which version does code compiled against the old library invoke? </p> </section> <section name="7012 - Method Added to Interface"> <p>Binary Severity: <code>ERROR</code></p> <p>Source Severity: <code>ERROR</code></p> <p> A method declaration has been added to the specified interface. This is always reported as a binary-compatibility error, but in practice the changed class <i>might</i> be used successfully with code compiled against the old interface depending upon usage patterns. </p> <p> Old code which invokes methods upon code compiled against the new (expanded) interface will continue to work without issues. And old code which implements the old version of the interface will also continue to work correctly as long as no code attempts to invoke any of the newly-added methods against that instance. But code which (validly) invokes one of the new methods in the interface against an object which implements only the old version of the interface will cause an AbstractMethodError to be thrown at the time the method invocation is attempted. </p> <p> Adding a method to an interface is always reported as an ERROR, because classes that implement that interface must now be modified to implement the declared method. </p> </section> <section name="7013 - Abstract Method Added to Class"> <p>Binary Severity: <code>ERROR</code></p> <p>Source Severity: <code>ERROR</code></p> <p> An abstract method declaration has been added to the specified class. This is always reported as a binary-compatibility error, but in practice the changed class <i>might</i> be used successfully with code compiled against the old class depending upon usage patterns. </p> <p> If instances of objects compiled against the old class are created, then their methods can be invoked without problems. But if the newly-added abstract method is ever invoked, then an AbstractMethodError is thrown at the time the method invocation is attempted. </p> </section> <section name="7014 - Method now final"> <p>Severity: <code>ERROR</code></p> <p> The method was previously non-final, and is now final. Subclasses of this class will no longer compile or run. </p> <p> When the old class containig this method was final (explicitly or by only providing private constructors) then subclasses cannot exist. Clirr currently does not check for this situation, so this will raise a false alarm in some corner cases. </p> </section> <section name="7015 - Method now non-final"> <p>Severity: <code>INFO</code></p> <p> The method was previously final, and is now non-final. This is always a binary-compatible change. </p> </section> <section name="8000 - Class Added"> <p>Severity: <code>INFO</code></p> <p> The new version of the library has a class which was not present in the old version. </p> </section> <section name="8001 - Class Removed"> <p>Severity: <code>ERROR</code></p> <p> The new version of the library no longer contains the specified class. </p> </section> <section name="10000 - Class Format Version Increased"> <p>Severity: <code>ERROR</code></p> <p> The new class is compiled with a higher "-target" compiler setting. This means that library users must upgrade their Java compiler and/or JVM in order to be able to use the new library version. </p> </section> <section name="10001 - Class Format Version Decreased"> <p>Severity: <code>INFO</code></p> <p> The new class is compiled with a lower "-target" compiler setting. Newer Java compilers and JVMs versions support all previous class file formats, so this is a binary and source compatible change. </p> </section> </section> </body> </document> --- NEW FILE --- <?xml version="1.0" encoding="ISO-8859-1"?> <document> <properties> <title>Clirr Ant Task</title> <author>Lars Kühne</author> </properties> <body> <section name="Running Clirr as an Ant Task"> <p> The clirr-core module contains an <a href="http://ant.apache.org">Ant</a> task. The following text assumes that you are familiar with Ant. To run clirr, you typically </p> <ul> <li>compile the current version of the library you want to check, resulting in one or more jar file</li> <li>tell ant about the clirr ant task</li> <li>download the compatibility baseline release of your software from a central location via http (if it is not available in your local filesystem already)</li> <li>run the clirr task</li> </ul> <p> To do this you will need an ant snippet similar to the following: </p> <source> <target name="checkbinarycompatibility" depends="build"> <!-- buildtools.classpath should either contain clirr-core-uber.jar or alternatively clirr-core.jar and the libraries it depends on --> <taskdef classpathref="buildtools.classpath" resource="clirrtask.properties"/> <property name="jar.baseline" value="${ant.project.name}-${compatibility.baseline.version}.jar"/> <get src="${url.libbase}/${ant.project.name}/${jar.baseline}" dest="build/tmp/${jar.baseline}"/> <clirr> <origfiles dir="build/tmp" includes="${jar.baseline}"/> <newfiles dir="build/lib" includes="${jar.buildresult}"/> <!-- <formatter type="xml" outfile="build/clirr.xml" /> --> <!-- TODO: example for 3rd party classpath --> </clirr> </target> </source> </section> <section name="Parameters"> <table> <tr> <td>Attribute</td> <td>Description</td> <td>Required</td> <td>Default</td> </tr> <tr> <td>failOnBinWarning</td> <td>Whether task execution should fail (break the build) on warnings about binary compatibility issues</td> <td>No</td> <td>No</td> </tr> <tr> <td>failOnBinError</td> <td>Whether task execution should fail (break the build) on binary compatibility errors</td> <td>No</td> <td>Yes</td> </tr> <tr> <td>failOnSrcWarning</td> <td>Whether task execution should fail (break the build) on warnings about source code compatibility issues</td> <td>No</td> <td>No</td> </tr> <tr> <td>failOnSrcError</td> <td>Whether task execution should fail (break the build) on source compatibility errors</td> <td>No</td> <td>Yes</td> </tr> </table> </section> <section name="Parameters specified as nested elements"> <section name="newFiles"> <p> A <a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a> that describes the current version that should be checked against the compatibility baseline. </p> <p> Clirr works with FileSets instead of individual jar files to allow splitting up or combining library distributions. An example is log4j, presumably the 1.3.0 release will split up the earlier log4j.jar into several jar files. </p> </section> <section name="origFiles"> <p> A <a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a> that describes the compatibility baseline to check against. </p> </section> <section name="newClassPath"> <p> The 3rd party <a href="http://ant.apache.org/manual/using.html#path">ClassPath</a> that is referenced by the checked library version (newFiles). Any class or interface that occurs as a baseclass, parameter type or method return type must be included here. </p> </section> <section name="origClassPath"> <p> The 3rd party <a href="http://ant.apache.org/manual/using.html#path">ClassPath</a> that is referenced by the compatibility baseline version (origFiles). Any class or interface that occurs as a baseclass, parameter type or method return type must be included here. </p> <p> Often the origClassPath is the same as the newClassPath. In these cases you can specify these paths using the refid attribute to avoid duplicating the classpath information. Please refer to the <a href="http://ant.apache.org/manual/using.html#path">ant manual</a> for details. </p> </section> <section name="formatter"> <p> A formatter that generates Clirr output. Multiple formatters can be specified. Available attributes for each formatter element: </p> <table> <tr> <td>Attribute</td> <td>Description</td> <td>Required</td> <td>Default</td> </tr> <tr> <td>type</td> <td>The formatter type. Available types are <em>plain</em> and <em>xml</em></td> <td>No</td> <td>plain</td> </tr> <tr> <td>outfile</td> <td>The file to write to. If not specified, output is written to stdout</td> <td>No</td> <td>stdout</td> </tr> </table> </section> <p> If no formatter is specified, Clirr will write it's findings to stdout in plain format. </p> </section> <section name="apiclasses"> <p> A <a href="http://ant.apache.org/manual/CoreTypes/patternset.html">PatternSet</a> that defines which classes form the API. By default all classes are included. </p> <p> The API is often only a subset from the set of public classes in a jar file. For example, the Eclipse project has <a href="http://www.eclipse.org/articles/Article-API%20use/eclipse-api-usage-rules.html">package naming conventions</a> that signal which classes must not be used outside a module, even though they are technically public. </p> <p> Example: </p> <source> <clirr> <origfiles dir="build/tmp" includes="${jar.baseline}"/> <newfiles dir="build/lib" includes="${jar.buildresult}"/> <apiclasses> <exclude name="**/internal/**"/> <exclude name="**/examples/**"/> <exclude name="**/tests/**"/> </apiclasses> </clirr> </source> </section> </body> </document> --- NEW FILE --- <?xml version="1.0" encoding="ISO-8859-1"?> <document> <properties> <title>Clirr Command-Line Usage</title> <author>Lars Kühne</author> </properties> <body> <section name="Running Clirr from the Command Line"> <p> Clirr provides an "uberjar", which bundles all the necessary code, including all required libraries, into a single executable jar file. Clirr can then be run from a commandline via the command: <code> java -jar clirr-core-@VE...@-u... </code> Running clirr with no command-line arguments will display the available options. </p> </section> </body> </document> --- NEW FILE --- <?xml version="1.0" encoding="ISO-8859-1"?> <document> <properties> <title>Clirr</title> <author>Lars Kühne</author> <meta name="keyword" content="java, api, diff, compare, jar, binary, compatibility, compatible, detect, incompatibility, incompatible"/> </properties> <body> <section name="What is it?"> <p> Clirr is a tool that checks Java libraries for binary and source compatibility with older releases. Basically you give it two sets of jar files and Clirr dumps out a list of changes in the public api. The Clirr Ant task can be configured to break the build if it detects incompatible api changes. In a continuous integration process Clirr can automatically prevent accidental introduction of binary or source compatibility problems. </p> </section> <section name="Background"> <p> To learn more about binary compatibility of Java APIs the follwing articles provide some detailed background material: <ul> <li> the article <a href="http://eclipse.org/eclipse/development/java-api-evolution.html">Evolving Java-based APIs</a> on the Eclipse web site. </li> <li> the <a href="http://java.sun.com/docs/books/jls/second_edition/html/binaryComp.doc.html">Binary Compatibility</a> section in the Java Language specification. </li> </ul> </p> </section> <section name="Features"> <ul> <li>Report all API changes (currently only partially implemented)</li> <li>Evaluate each change wrt. binary and source compatibility</li> <li>support plain text and XML reports</li> <li>Flexible failure handling (warnings vs. errors, break the build or set error property)</li> </ul> </section> <section name="Name"> <p> The name clirr is derived from the binary compatibility property that a new release of a library/component should have (cited from the above mentioned Eclipse article): </p> <p> Pre-existing <em>C</em>lient binaries must <em>li</em>nk and <em>r</em>un with new <em>r</em>eleases of the Component without recompiling. </p> <p> You can also use clirr as a verb, as in <cite>Last night the build clirred</cite>, meaning that binary incompatibility problems were detected and broke the build. </p> </section> </body> </document> |
