'. '

TruffleSigtest

From APIDesign

Revision as of 18:37, 20 November 2015 by JaroslavTulach (Talk | contribs)
Jump to: navigation, search

API signature tests are part of Truffle project workflow since today! Let me describe what I have done, as similar changes are likely needed in any Java project that wants to use SignatureTests to keep backward compatibility of its APIs.

Contents

Identify Your API

TBD

The Right Tool

First and foremost one needs to select a signature testing tool. As my background is related to NetBeans, my choice was almost guaranteed. I decided to use NetBeans APITest.

Slight problem was that the tool hasn't been updated to JDK8 language constructs (e.g. default and static methods in interfaces). However, as NetBeans need to use the tool as well, I got a great help from Tomáš Zezula. He is currently working on switching the NetBeans codebase to JDK8 and he updated the APITest to deal properly with JDK8 features (see here and here). It is always good to build on shoulders of giants - e.g. use a tool that a mature project like NetBeans maintains.

Download the APITest from here.

Integrate into Build Process

Signature testing needs to be integrated into build process of your project - in case there is a violation with respect to BackwardCompatibility, the build should fail. As (almost) every big project "needs" its own build harness, the way to integrate differs. For example, NetBeans is using Ant based harness and thus one deals with the signature testing tool via Ant as described at netbeans:SignatureTest page.

The Truffle project (as well as Graal) is using Python based harness. As such I had to write a bit of Python code to integrate the APITest into it (see here). You basically need two operations:

  1. generate - which will take a snapshot of your API at a certain point of time (usually at a release time)
  2. check - which will compare the current state of your API with the existing snapshot

The way to invoke these operation in Truffle repository are like:

$ mx sigtest --generate
# generates following files
truffle/com.oracle.truffle.api.dsl/snapshot.sigtest
truffle/com.oracle.truffle.api.interop.java/snapshot.sigtest
truffle/com.oracle.truffle.api.interop/snapshot.sigtest
truffle/com.oracle.truffle.api.object/snapshot.sigtest
truffle/com.oracle.truffle.api/snapshot.sigtest
truffle/com.oracle.truffle.api.vm/snapshot.sigtest
 
# check whether there are any incompatible changes
$ mx sigtest --check binary
 
# check if there are any API changes
$ mx sigtest --check all

I've integrated the "--check binary" into so called gate check, so if there is an incompatible change, the build fails - see the changeset.


Setting the Snapshots Up

BackwardCompatibility is important between releases, so once you do a release (whatever that means), generate a snapshot of your API state. The most recent (e.g. JavaOne 2015) release of Truffle is 0.9, so I just did:

$ hg up -C truffle-0.9
$ mx sigtest --generate
$ hg add .
$ hg ci -m "Adding API snapshots as for version truffle-0.9 and enabling their check in the gate"

Here is how such snapshot files look like: changeset

Personal tools
buy