SigTest

(Difference between revisions)
 
(18 intermediate revisions not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
-
==[[APITest | APITest]] tool==
+
[[SigTest]] is the tool behind [[NetBeans]] [[SignatureTest | signature testing]] infrastructure. It checks for incompatibilities between different versions of the same [[API]].
-
This is the tool behind [[SignatureTest | SignatureTest]] infrastructure. It checks for incompatibilities and is currently done by [http://hg.netbeans.org/apitest/ NetBeans' own version] of an OpenJDK [https://sigtest.dev.java.net/ sigtest tool] tool. This adds a standard Ant task to check for binary backward compatibility, mutual signature compatibility. The binary compatibility check ignores generic types. Its [http://hg.netbeans.org/apitest/ sources] are distributed together with its Mercurial repository and are available under GPL version 2.
+
== New Home ==
-
====Download====
+
Please continue at https://github.com/jtulach/netbeans-apitest#readme
 +
that is the new home since NetBeans migrated to Apache.
 +
 
 +
== Old Content Follows ==
 +
 
 +
 
 +
[[NetBeans]] uses the [[APITest]] tool as an Ant task to check for binary backward compatibility and mutual signature compatibility. There is however also a version released as a [http://search.maven.org/#search|ga|1|a%3A%22sigtest-maven-plugin%22 Maven Plugin] ready for use in your own project. The [https://github.com/jtulach/netbeans-apitest sources] were converted to GitHub repository and are available under GPL version 2.
 +
 
 +
=== Use in Maven ===
 +
 
 +
The [http://search.maven.org/#search|ga|1|a%3A%22sigtest-maven-plugin%22 Maven Plugin] is available on [http://search.maven.org/#search|ga|1|a%3A%22sigtest-maven-plugin%22 Maven central] thus it is easily embeddable it into your own project.
 +
 
 +
==== Generate the Signature File ====
 +
 
 +
The first thing to do is to generate snapshot of [[API]] of your library - e.g. the signature file. Just add following into your own ''pom.xml'' file:
 +
 
 +
<source lang="xml">
 +
<plugin>
 +
  <groupId>org.netbeans.tools</groupId>
 +
  <artifactId>sigtest-maven-plugin</artifactId>
 +
  <version>1.2</version>
 +
  <executions>
 +
    <execution>
 +
      <goals>
 +
        <goal>generate</goal>
 +
      </goals>
 +
    </execution>
 +
  </executions>
 +
  <configuration>
 +
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
 +
  </configuration>
 +
</plugin>
 +
</source>
 +
 
 +
with just this change the [[API]] of your classes in the listed packages is going to be recorded into a ''.sigtest'' file and included as an artefact of your project when you invoke `mvn install`.
 +
 
 +
For example libraries of [[Html4Java]] [[NetBeans]] [[API]] [http://repo1.maven.org/maven2/org/netbeans/html/net.java.html.json/1.3/ have the sigtest file] attached in Maven central with [http://hg.netbeans.org/html4j/rev/833829b33779 this changeset].
 +
 
 +
==== Check Against Signature File in a Repository ====
 +
 
 +
Once the ''sigfile'' is part of a Maven repository, you want to check your new APIs against that [[API]] ''snapshot'' to make sure you are not making incompatible changes. Try the following:
 +
 
 +
<source lang="xml">
 +
<plugin>
 +
  <groupId>org.netbeans.tools</groupId>
 +
  <artifactId>sigtest-maven-plugin</artifactId>
 +
  <version>1.2</version>
 +
  <executions>
 +
    <execution>
 +
      <goals>
 +
        <goal>check</goal>
 +
      </goals>
 +
    </execution>
 +
  </executions>
 +
  <configuration>
 +
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
 +
    <releaseVersion>1.3</releaseVersion>
 +
  </configuration>
 +
</plugin>
 +
</source>
 +
 
 +
The difference is the goal - e.g. '''check''' and also the need to specify '''releaseVersion''' - that is the identification of the previously released version of your library that you want to check compatibility against.
 +
 
 +
And that is all! To verify the setup is correct, try to remove a method or do some other incompatible change. When I tried and executed ''mvn install'' I got a build failure
 +
 
 +
<source lang="bash">
 +
SignatureTest report
 +
Base version: 1.3
 +
Tested version: 2.0-SNAPSHOT
 +
Check mode: bin [throws removed]
 +
Constant checking: on
 +
 
 +
 
 +
Class net.java.html.json.Models
 +
  "E1.2 - API type removed" : method public final static void net.java.html.json.Models.applyBindings(java.lang.Object,java.lang.String)
 +
 
 +
 
 +
 
 +
target/surefire-reports/sigtest/TEST-json-2.0-SNAPSHOT.xml: 1 failures in /.m2/repository/json/1.3/json-1.3.sigfile
 +
------------------------------------------------------------------------
 +
BUILD FAILURE
 +
</source>
 +
 
 +
This is the way [[Html4Java]] enabled signature testing: see [http://hg.netbeans.org/html4j/rev/031e46d048d8 changeset] mixing both goals together.
 +
 
 +
==== Fail on Error ====
 +
 
 +
You may want to control whether a failure in signature test should be fatal or not. Do it with:
 +
 
 +
<source lang="xml">
 +
  <configuration>
 +
    <failOnError>false</failOnError>
 +
 
 +
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
 +
    <releaseVersion>1.3</releaseVersion>
 +
  </configuration>
 +
</source>
 +
 
 +
With this configuration the test will be performed and output printed, but the build will go on. This may be useful when one needs to do an incompatible change and wants to disable the check until next version is published.
 +
 
 +
==== Prevent Any Change ====
 +
 
 +
By default the plugin verifies there are no '''incompatible''' changes. However compatible changes are allowed. Sometimes it is useful to prevent any changes altogether (when creating a bugfix release, for example), then try:
 +
 
 +
<source lang="xml">
 +
  <configuration>
 +
    <action>strictcheck</action>
 +
 
 +
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
 +
    <releaseVersion>1.3</releaseVersion>
 +
  </configuration>
 +
</source>
 +
 
 +
with the '''action''' option set to ''strictcheck'' the plugin will detect any [[API]] change and fail even if it is compatible.
 +
 
 +
== Who's Using [[SigTest]] ==
 +
 
 +
[[NetBeans]] [[SigTest]] is used by:
 +
* [[NetBeans]] uses it as an Ant task
 +
* [[Html4Java]] [[API]]s use it as Maven plugin
 +
* Oracle Labs [https://github.com/graalvm/truffle Truffle project] integrates it into [[apidesign:TruffleSigtest|their own build tool]]
 +
* [http://dukescript.com DukeScript] project for its [https://github.com/dukescript/DefinitelyTyped Definitely Typed Java API] for all JavaScript libraries
 +
 
 +
== Develop ==
Binary Builds are available from our [http://deadlock.netbeans.org/hudson/job/apitest/ hudson builder]. Get the sources with
Binary Builds are available from our [http://deadlock.netbeans.org/hudson/job/apitest/ hudson builder]. Get the sources with
-
<pre>
+
<source lang="bash">
   hg clone http://hg.netbeans.org/apitest/
   hg clone http://hg.netbeans.org/apitest/
   cd apitest
   cd apitest
   ant jar test
   ant jar test
   # open in NetBeans
   # open in NetBeans
-
</pre>
+
</source>
 +
 
 +
Contact the developer via email jtulach (at) netbeans.org - and don't forget to read [[apidesign:TheAPIBook|Practical API Design]] book.
 +
 
 +
<!--
====Why another API test tool?====
====Why another API test tool?====
Line 24: Line 151:
* '''All were accepted'''.
* '''All were accepted'''.
 +
 +
-->

Current revision as of 05:59, 10 April 2019

SigTest is the tool behind NetBeans signature testing infrastructure. It checks for incompatibilities between different versions of the same API.

New Home

Please continue at https://github.com/jtulach/netbeans-apitest#readme
that is the new home since NetBeans migrated to Apache.

Old Content Follows

NetBeans uses the APITest tool as an Ant task to check for binary backward compatibility and mutual signature compatibility. There is however also a version released as a Maven Plugin ready for use in your own project. The sources were converted to GitHub repository and are available under GPL version 2.

Use in Maven

The Maven Plugin is available on Maven central thus it is easily embeddable it into your own project.

Generate the Signature File

The first thing to do is to generate snapshot of API of your library - e.g. the signature file. Just add following into your own pom.xml file:

<plugin>
  <groupId>org.netbeans.tools</groupId>
  <artifactId>sigtest-maven-plugin</artifactId>
  <version>1.2</version>
  <executions>
    <execution>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
  </configuration>
</plugin>

with just this change the API of your classes in the listed packages is going to be recorded into a .sigtest file and included as an artefact of your project when you invoke `mvn install`.

For example libraries of Html4Java NetBeans API have the sigtest file attached in Maven central with this changeset.

Check Against Signature File in a Repository

Once the sigfile is part of a Maven repository, you want to check your new APIs against that API snapshot to make sure you are not making incompatible changes. Try the following:

<plugin>
  <groupId>org.netbeans.tools</groupId>
  <artifactId>sigtest-maven-plugin</artifactId>
  <version>1.2</version>
  <executions>
    <execution>
      <goals>
        <goal>check</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
    <releaseVersion>1.3</releaseVersion>
  </configuration>
</plugin>

The difference is the goal - e.g. check and also the need to specify releaseVersion - that is the identification of the previously released version of your library that you want to check compatibility against.

And that is all! To verify the setup is correct, try to remove a method or do some other incompatible change. When I tried and executed mvn install I got a build failure

SignatureTest report
Base version: 1.3
Tested version: 2.0-SNAPSHOT
Check mode: bin [throws removed]
Constant checking: on
 
 
Class net.java.html.json.Models
  "E1.2 - API type removed" : method public final static void net.java.html.json.Models.applyBindings(java.lang.Object,java.lang.String)
 
 
 
target/surefire-reports/sigtest/TEST-json-2.0-SNAPSHOT.xml: 1 failures in /.m2/repository/json/1.3/json-1.3.sigfile
------------------------------------------------------------------------
BUILD FAILURE

This is the way Html4Java enabled signature testing: see changeset mixing both goals together.

Fail on Error

You may want to control whether a failure in signature test should be fatal or not. Do it with:

  <configuration>
    <failOnError>false</failOnError>
 
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
    <releaseVersion>1.3</releaseVersion>
  </configuration>

With this configuration the test will be performed and output printed, but the build will go on. This may be useful when one needs to do an incompatible change and wants to disable the check until next version is published.

Prevent Any Change

By default the plugin verifies there are no incompatible changes. However compatible changes are allowed. Sometimes it is useful to prevent any changes altogether (when creating a bugfix release, for example), then try:

  <configuration>
    <action>strictcheck</action>
 
    <packages>org.yourcompany.app.api,org.yourcompany.help.api</packages>
    <releaseVersion>1.3</releaseVersion>
  </configuration>

with the action option set to strictcheck the plugin will detect any API change and fail even if it is compatible.

Who's Using SigTest

NetBeans SigTest is used by:

Develop

Binary Builds are available from our hudson builder. Get the sources with

  hg clone http://hg.netbeans.org/apitest/
  cd apitest
  ant jar test
  # open in NetBeans

Contact the developer via email jtulach (at) netbeans.org - and don't forget to read Practical API Design book.


Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo