japi-compliance-checker - Check backward compatibility of a Java
library API
- Java API Compliance Checker (japi-compliance-checker) Check backward
compatibility of a Java library API
- Java API Compliance Checker (JAPICC) is a tool for checking backward
binary/source compatibility of a Java library API. The tool checks class
declarations of old and new versions and analyzes changes that may break
compatibility: removed class members, added abstract methods, etc.
- Break of the binary compatibility may result in crash or incorrect
behavior of existing clients built with an old library version if they run
with a new one. Break of the source compatibility may result in
recompilation errors with a new library version.
- The tool is intended for developers of software libraries and maintainers
of operating systems who are interested in ensuring backward
compatibility, i.e. allow old clients to run or to be recompiled with
newer library versions.
- This tool is free software: you can redistribute it and/or modify it under
the terms of the GNU LGPL.
- japi-compliance-checker [options]
EXAMPLE_(1):">EXAMPLE_(1):">EXAMPLE
(1):
- japi-compliance-checker OLD.jar NEW.jar
EXAMPLE_(2):">EXAMPLE_(2):">EXAMPLE
(2):
- japi-compliance-checker OLD.jmod NEW.jmod
EXAMPLE_(3):">EXAMPLE_(3):">EXAMPLE
(3):
- 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) OR JMOD(s)/ /path2/to/JAR(s) OR JMOD(s)/ ...
- </archives>
-h|-help
- Print this help.
-v|-version
- Print version information.
-dumpversion
- Print the tool version (2.4) and don't do anything else.
-l|-library NAME
- Library name (without version).
-old|-d1 PATH
- Descriptor of the 1st (old) library version. It may be one of the
following:
- 1. Java archive (*.jar or *.jmod) 2. XML-descriptor (VERSION.xml
file):
- <version>
- 1.0
- </version>
- <archives>
- /path1/to/JAR(s) OR JMOD(s)/ /path2/to/JAR(s) OR JMOD(s)/
- ...
- </archives>
- ...
- 3. API dump generated by -dump option
- If you are using *.jar or *.jmod as a descriptor then you should specify
version numbers with -v1 and -v2 options too. If version
numbers are not specified then the tool will try to detect them
automatically.
-new|-d2 PATH
- Descriptor of the 2nd (new) library version.
-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 regular expression.
-skip-internal-types PATTERN
- Do not check types (classes and interfaces) matched by the regular
expression. It's matched against full qualified type names (e.g.
'org.xyz.Name<T>'). It has to match any part of type name.
-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. PATH is the path to the Java archive or XML descriptor of the
library.
-check-annotations
- Check for changes in annotations like in any other interfaces.
-check-packages PATTERN
- Check packages matched by the regular expression. Other packages will not
be checked.
-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
- List of classes that should not be checked.
-skip-packages PATH
- List of packages that should not be checked.
-non-impl PATH
- List of interfaces that should not be implemented by users.
-non-impl-all
- All interfaces should not be implemented by users.
-short
- Do not list added/removed methods.
-dump-path PATH
- Specify a *.dump file path where to generate an API dump. Default:
- api_dumps/LIB_NAME/VERSION/API.dump
-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.
-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.
- Compatibility report will be generated to:
- compat_reports/LIB_NAME/V1_to_V2/compat_report.html
- 0 - Compatible. The tool has run without any errors. non-zero -
Incompatible or the tool has run with errors.
- https://lvc.github.io/japi-compliance-checker/
https://github.com/lvc/japi-compliance-checker
Written by Andrey Ponomarenko.
Copyright © 2018 Andrey Ponomarenko's ABI Laboratory
License: LGPLv2.1+ <http://www.gnu.org/licenses/> This program is free
software: you can redistribute it and/or modify it.