JAPI-COMPLIANCE-CHECKER(1)

NAME
japi-compliance-checker - 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 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.

  USAGE:

    japi-compliance-checker [options]

  EXAMPLE (1):

    japi-compliance-checker OLD.jar NEW.jar

  EXAMPLE (2):

    japi-compliance-checker OLD.jmod NEW.jmod

  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>

  INFORMATION OPTIONS:

-h|-help

    Print this help.

-v|-version

    Print version information.

-dumpversion

    Print the tool version (2.4) and don't do anything else.

  GENERAL OPTIONS:

-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.

  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 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.

  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.

  MORE INFO:

    https://lvc.github.io/japi-compliance-checker/ https://github.com/lvc/japi-compliance-checker

AUTHOR
Written by Andrey Ponomarenko.

COPYRIGHT
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.