japi-compliance-checker(1) Check backward compatibility of a Java library API

DESCRIPTION

NAME:

Java API Compliance Checker (japi-compliance-checker) Check backward compatibility of a Java library API

DESCRIPTION:

Java API Compliance Checker (JAPICC) is a tool for checking backward binary/source compatibility of a Java library API. The tool checks classes declarations of old and new versions and analyzes changes that may break compatibility: removed class members, added abstract methods, etc. Breakage of the binary compatibility may result in crashing or incorrect behavior of existing clients built with an old version of a library if they run with a new one. Breakage of the source compatibility may result in recompilation errors with a new library version.
JAPICC is intended for library developers and operating system maintainers who are interested in ensuring backward compatibility (i.e. allow old clients to run or to be recompiled with a new version of a library).
This tool is free software: you can redistribute it and/or modify it under the terms of the GNU LGPL or GNU GPL.

USAGE:

japi-compliance-checker [options]

EXAMPLE:

japi-compliance-checker OLD.jar NEW.jar
OR
japi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml OLD.xml and NEW.xml are XML-descriptors:
<version>
1.0
</version>
<archives>
/path1/to/JAR(s)/ /path2/to/JAR(s)/ ...
</archives>

INFORMATION OPTIONS:

-h|-help
Print this help.
-v|-version
Print version information.
-dumpversion
Print the tool version (1.8) and don't do anything else.

GENERAL OPTIONS:

-l|-lib|-library NAME
Library name (without version).
-d1|-old|-o PATH
Descriptor of 1st (old) library version. It may be one of the following:
1. Java ARchive (*.jar) 2. XML-descriptor (VERSION.xml file):
<version>
1.0
</version>
<archives>
/path1/to/JAR(s)/ /path2/to/JAR(s)/
...
</archives>
...
3. API dump generated by -dump option
If you are using 1, 4-6 descriptor types then you should specify version numbers with -v1 and -v2 options too.
If you are using *.jar as a descriptor then the tool will try to get implementation version from MANIFEST.MF file.
-d2|-new|-n PATH
Descriptor of 2nd (new) library version.

EXTRA OPTIONS:

-client|-app PATH
This option allows to specify the client Java ARchive that should be checked for portability to the new library version.
-binary|-bin
Show "Binary" compatibility problems only. Generate report to "bin_compat_report.html".
-source|-src
Show "Source" compatibility problems only. Generate report to "src_compat_report.html".
-v1|-version1 NUM
Specify 1st API version outside the descriptor. This option is needed if you have prefered an alternative descriptor type (see -d1 option).
In general case you should specify it in the XML descriptor:
<version>
VERSION
</version>
-v2|-version2 NUM
Specify 2nd library version outside the descriptor.
-vnum NUM
Specify the library version in the generated API dump.
-s|-strict
Treat all API compatibility warnings as problems.
-keep-internal
Do not skip checking of these packages:
*impl* *internal* *examples*
-skip-internal-packages PATTERN
Do not check packages matched by the pattern.
-skip-internal-types PATTERN
Do not check types (classes and interfaces) matched by the pattern.
-dump|-dump-api PATH
Dump library API to gzipped TXT format file. You can transfer it anywhere and pass instead of the descriptor. Also it may be used for debugging the tool. Compatible dump versions: 2.0<=V<=2.0
-classes-list PATH
This option allows to specify a file with a list of classes that should be checked, other classes will not be checked.
-annotations-list PATH
Specifies a file with a list of annotations. The tool will check only classes annotated by the annotations from the list. Other classes will not be checked.
-skip-annotations-list PATH
Skip checking of classes annotated by the annotations in the list.
-skip-deprecated
Skip analysis of deprecated methods and classes.
-skip-classes PATH
This option allows to specify a file with a list of classes that should not be checked.
-skip-packages PATH
This option allows to specify a file with a list of packages that should not be checked.
-short
Do not list added/removed methods.
-dump-path PATH
Specify a *.api.tar.gz or *.api file path where to generate an API dump. Default:
abi_dumps/LIB_NAME/LIB_NAME_VERSION.api.tar.gz
-report-path PATH
Path to compatibility report. Default:
compat_reports/LIB_NAME/V1_to_V2/compat_report.html
-bin-report-path PATH
Path to "Binary" compatibility report. Default:
compat_reports/LIB_NAME/V1_to_V2/bin_compat_report.html
-src-report-path PATH
Path to "Source" compatibility report. Default:
compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html
-quick
Quick analysis. Disabled:
- analysis of method parameter names - analysis of class field values - analysis of usage of added abstract methods - distinction of deprecated methods and classes
-sort
Enable sorting of data in API dumps.
-show-access
Show access level of non-public methods listed in the report.
-hide-templates
Hide template parameters in the report.
-hide-packages
-minimal
Do nothing.
-show-packages
Show package names in the report.
-limit-affected LIMIT
The maximum number of affected methods listed under the description of the changed type in the report.
-compact
Try to simplify formatting and reduce size of the report (for a big set of changes).
-added-annotations
Apply filters by annotations only to new version of the library.
-removed-annotations
Apply filters by annotations only to old version of the library.
-count-methods PATH
Count total public methods in the API dump.
-dep1 PATH
-dep2 PATH
Path to the API dump of the required dependency archive. It will be used to resolve overwritten methods and more.
-old-style
Generate old-style report.

OTHER OPTIONS:

-test
Run internal tests. Create two incompatible versions of a sample library and run the tool to check them for compatibility. This option allows to check if the tool works correctly in the current environment.
-debug
Debugging mode. Print debug info on the screen. Save intermediate analysis stages in the debug directory:
debug/LIB_NAME/VER/
Also consider using -dump option for debugging the tool.
-title NAME
Change library name in the report title to NAME. By default will be displayed a name specified by -l option.
-jdk-path PATH
Path to the JDK install tree (e.g. ,/usr/lib/jvm/java-7-openjdk-amd64/).
-external-css PATH
Generate CSS styles file to PATH. This helps to save space when generating thousands of reports.
-external-js PATH
Generate JS script file to PATH.

REPORT:

Compatibility report will be generated to:
compat_reports/LIB_NAME/V1_to_V2/compat_report.html

EXIT CODES:

0 - Compatible. The tool has run without any errors. non-zero - Incompatible or the tool has run with errors.

AUTHOR

Written by Andrey Ponomarenko.

COPYRIGHT

Copyright © 2016 Andrey Ponomarenko's ABI Laboratory License: LGPL or GPL <http://www.gnu.org/licenses/> This program is free software: you can redistribute it and/or modify it.