Note: These pages are being reviewed.
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 sigtest-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 sigtest Maven Plugin is available on sigtest-maven-plugin at 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:
-
NetBeans uses it as an Ant task
-
Html4Java APIs use it as Maven plugin
-
Oracle Labs Truffle project integrates it into their own build tool.
-
DukeScript project for its Definitely Typed Java API for all JavaScript libraries
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.
The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation. This page was exported from http://wiki.netbeans.org/SigTest , that was last modified by NetBeans user Jtulach on 2019-04-10T05:59:08Z. This document was automatically converted to the AsciiDoc format on 2020-03-15, and needs to be reviewed. |