Ubuntu Manpage: japi-compliance-checker - Check backward compatibility of a Java library API

Provided by: japi-compliance-checker_1.4.3-1_all

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 (Java ACC) 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.

Java ACC 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

japi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml OLD.xml and NEW.xml are
XML-descriptors:

1.0

</version>

/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.4.3) 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):

1.0

</version>

/path1/to/JAR(s)/ /path2/to/JAR(s)/

...

</archives>

...

3. API dump generated by -dump option 4. Directory with Java ARchives 5. Comma
separated list of Java ARchives 6. Comma separated list of directories with Java
ARchives

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

Show "Binary" compatibility problems only. Generate report to
"bin_compat_report.html".

-source

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>

-v2|-version2 NUM

Specify 2nd library version outside the descriptor.

-s|-strict

Treat all API compatibility warnings as problems.

-keep-internal

Do not skip checking of these packages:

*impl* *internal* *examples* *com.oracle* *com.sun* *COM.rsa* *sun* *sunw*

-skip-internal PATTERN

Do not check internal packages 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: 1.0<=V<=1.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 this list. Other classes will not be checked.

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

Generate short report without 'Added Methods' section.

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

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

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 INFORMATION:
http://ispras.linuxbase.org/index.php/Java_API_Compliance_Checker
https://github.com/lvc/japi-compliance-checker

AUTHOR

       Written by Andrey Ponomarenko.

COPYRIGHT

       Copyright   ©   2015   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.

japi-compliance-checker API Compliance CheNovemberv2015C) 1.4.3        JAPI-COMPLIANCE-CHECKER(1)