diff options
author | Ilpo Ruotsalainen <ilpo.ruotsalainen@oath.com> | 2018-11-28 14:32:00 +0100 |
---|---|---|
committer | Ilpo Ruotsalainen <ilpo.ruotsalainen@oath.com> | 2018-11-28 15:54:45 +0100 |
commit | 54bf0d9de1f98a0e1e987d74c7af723ad7666e14 (patch) | |
tree | 017fa19ef8f2553c68c57f56e21101c840eb6e72 | |
parent | 66815538b85292810f64831eb5bc0864111ce4b5 (diff) |
Add some usage documentation.
-rw-r--r-- | abi-check-plugin/README.md | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/abi-check-plugin/README.md b/abi-check-plugin/README.md new file mode 100644 index 00000000000..23a68a94783 --- /dev/null +++ b/abi-check-plugin/README.md @@ -0,0 +1,56 @@ +# abi-check-plugin + +Maven plugin for ensuring project ABI stability. + +## Theory of operation + +The project artifact JAR is scanned for class files. The resulting package tree is scanned for +packages annotated with configured annotation denoting a package that is considered public ABI. +Classes in those packages are scanned for their visible ABI and the result is compared against +expected ABI (stored in a JSON file) and possible discrepancies are reported. + +## What is considered visible ABI + +Visible ABI is considered to be classes, methods and fields that are accessible from other JAR +files without use of reflection or other tricks. + +## Setup + +### Add plugin to build + +Add the plugin to `<plugins>` in the project `pom.xml`, with an execution of `abicheck` goal. This +goal has to be executed in a phase where the project artifact JAR is available, the recommended +phase is `package`. + +Example: +``` +<plugin> + <groupId>com.yahoo.vespa</groupId> + <artifactId>abi-check-plugin</artifactId> + <configuration> + <publicApiAnnotation>com.yahoo.api.annotations.PublicApi</publicApiAnnotation> + </configuration> + <executions> + <execution> + <phase>package</phase> + <goals> + <goal>abicheck</goal> + </goals> + </execution> + </executions> +</plugin> +``` + +### Configuration parameters + + * **publicApiAnnotation** (required) + Fully qualified class name of the annotation that denotes a public API package. + * **specFileName** (optional, default: `abi-spec.json`) + File name relative to project root from which to read the expected ABI spec from. + +## Updating the expected ABI spec + +To automatically generate the expected ABI spec from the current ABI of the project, define +property `abicheck.writeSpec` when running the relevant phase. + +Example: `mvn package -Dabicheck.writeSpec` |