.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.46.4.
.TH JAPI-COMPLIANCE-CHECKER "1" "July 2016" "japi-compliance-checker API Compliance Checker (JAPICC) 1.8" "User Commands"
.SH NAME
japi-compliance-checker \- Check backward compatibility of a Java library API
.SH DESCRIPTION
.SS "NAME:"
.IP
Java API Compliance Checker (japi\-compliance\-checker)
Check backward compatibility of a Java library API
.SS "DESCRIPTION:"
.IP
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.
.IP
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).
.IP
This tool is free software: you can redistribute it and/or modify it
under the terms of the GNU LGPL or GNU GPL.
.SS "USAGE:"
.IP
japi\-compliance\-checker [options]
.SS "EXAMPLE:"
.IP
japi\-compliance\-checker OLD.jar NEW.jar
.IP
OR
.IP
japi\-compliance\-checker \fB\-lib\fR NAME \fB\-old\fR OLD.xml \fB\-new\fR NEW.xml
OLD.xml and NEW.xml are XML\-descriptors:
.IP
<version>
.IP
1.0
.IP
</version>
.IP
<archives>
.IP
/path1/to/JAR(s)/
/path2/to/JAR(s)/
\&...
.IP
</archives>
.SS "INFORMATION OPTIONS:"
.HP
\fB\-h\fR|\-help
.IP
Print this help.
.HP
\fB\-v\fR|\-version
.IP
Print version information.
.HP
\fB\-dumpversion\fR
.IP
Print the tool version (1.8) and don't do anything else.
.SS "GENERAL OPTIONS:"
.HP
\fB\-l\fR|\-lib|\-library NAME
.IP
Library name (without version).
.HP
\fB\-d1\fR|\-old|\-o PATH
.IP
Descriptor of 1st (old) library version.
It may be one of the following:
.IP
1. Java ARchive (*.jar)
2. XML\-descriptor (VERSION.xml file):
.IP
<version>
.IP
1.0
.IP
</version>
.IP
<archives>
.IP
/path1/to/JAR(s)/
/path2/to/JAR(s)/
.IP
\&...
.IP
</archives>
.IP
\&...
.IP
3. API dump generated by \fB\-dump\fR option
.IP
If you are using 1, 4\-6 descriptor types then you should
specify version numbers with \fB\-v1\fR and \fB\-v2\fR options too.
.IP
If you are using *.jar as a descriptor then the tool will try to
get implementation version from MANIFEST.MF file.
.HP
\fB\-d2\fR|\-new|\-n PATH
.IP
Descriptor of 2nd (new) library version.
.SS "EXTRA OPTIONS:"
.HP
\fB\-client\fR|\-app PATH
.IP
This option allows to specify the client Java ARchive that should be
checked for portability to the new library version.
.HP
\fB\-binary\fR|\-bin
.IP
Show "Binary" compatibility problems only.
Generate report to "bin_compat_report.html".
.HP
\fB\-source\fR|\-src
.IP
Show "Source" compatibility problems only.
Generate report to "src_compat_report.html".
.HP
\fB\-v1\fR|\-version1 NUM
.IP
Specify 1st API version outside the descriptor. This option is needed
if you have prefered an alternative descriptor type (see \fB\-d1\fR option).
.IP
In general case you should specify it in the XML descriptor:
.IP
<version>
.IP
VERSION
.IP
</version>
.HP
\fB\-v2\fR|\-version2 NUM
.IP
Specify 2nd library version outside the descriptor.
.HP
\fB\-vnum\fR NUM
.IP
Specify the library version in the generated API dump.
.HP
\fB\-s\fR|\-strict
.IP
Treat all API compatibility warnings as problems.
.HP
\fB\-keep\-internal\fR
.IP
Do not skip checking of these packages:
.IP
*impl*
*internal*
*examples*
.HP
\fB\-skip\-internal\-packages\fR PATTERN
.IP
Do not check packages matched by the pattern.
.HP
\fB\-skip\-internal\-types\fR PATTERN
.IP
Do not check types (classes and interfaces) matched by the pattern.
.HP
\fB\-dump\fR|\-dump\-api PATH
.IP
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
.HP
\fB\-classes\-list\fR PATH
.IP
This option allows to specify a file with a list
of classes that should be checked, other classes will not be checked.
.HP
\fB\-annotations\-list\fR PATH
.IP
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.
.HP
\fB\-skip\-annotations\-list\fR PATH
.IP
Skip checking of classes annotated by the annotations in the list.
.HP
\fB\-skip\-deprecated\fR
.IP
Skip analysis of deprecated methods and classes.
.HP
\fB\-skip\-classes\fR PATH
.IP
This option allows to specify a file with a list
of classes that should not be checked.
.HP
\fB\-skip\-packages\fR PATH
.IP
This option allows to specify a file with a list
of packages that should not be checked.
.HP
\fB\-short\fR
.IP
Do not list added/removed methods.
.HP
\fB\-dump\-path\fR PATH
.IP
Specify a *.api.tar.gz or *.api file path where to generate an API dump.
Default:
.IP
abi_dumps/LIB_NAME/LIB_NAME_VERSION.api.tar.gz
.HP
\fB\-report\-path\fR PATH
.IP
Path to compatibility report.
Default:
.IP
compat_reports/LIB_NAME/V1_to_V2/compat_report.html
.HP
\fB\-bin\-report\-path\fR PATH
.IP
Path to "Binary" compatibility report.
Default:
.IP
compat_reports/LIB_NAME/V1_to_V2/bin_compat_report.html
.HP
\fB\-src\-report\-path\fR PATH
.IP
Path to "Source" compatibility report.
Default:
.IP
compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html
.HP
\fB\-quick\fR
.IP
Quick analysis.
Disabled:
.IP
\- analysis of method parameter names
\- analysis of class field values
\- analysis of usage of added abstract methods
\- distinction of deprecated methods and classes
.HP
\fB\-sort\fR
.IP
Enable sorting of data in API dumps.
.HP
\fB\-show\-access\fR
.IP
Show access level of non\-public methods listed in the report.
.HP
\fB\-hide\-templates\fR
.IP
Hide template parameters in the report.
.HP
\fB\-hide\-packages\fR
.HP
\fB\-minimal\fR
.IP
Do nothing.
.HP
\fB\-show\-packages\fR
.IP
Show package names in the report.
.HP
\fB\-limit\-affected\fR LIMIT
.IP
The maximum number of affected methods listed under the description
of the changed type in the report.
.HP
\fB\-compact\fR
.IP
Try to simplify formatting and reduce size of the report (for a big
set of changes).
.HP
\fB\-added\-annotations\fR
.IP
Apply filters by annotations only to new version of the library.
.HP
\fB\-removed\-annotations\fR
.IP
Apply filters by annotations only to old version of the library.
.HP
\fB\-count\-methods\fR PATH
.IP
Count total public methods in the API dump.
.HP
\fB\-dep1\fR PATH
.HP
\fB\-dep2\fR PATH
.IP
Path to the API dump of the required dependency archive. It will
be used to resolve overwritten methods and more.
.HP
\fB\-old\-style\fR
.IP
Generate old\-style report.
.SS "OTHER OPTIONS:"
.HP
\fB\-test\fR
.IP
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.
.HP
\fB\-debug\fR
.IP
Debugging mode. Print debug info on the screen. Save intermediate
analysis stages in the debug directory:
.IP
debug/LIB_NAME/VER/
.IP
Also consider using \fB\-dump\fR option for debugging the tool.
.HP
\fB\-title\fR NAME
.IP
Change library name in the report title to NAME. By default
will be displayed a name specified by \fB\-l\fR option.
.HP
\fB\-jdk\-path\fR PATH
.IP
Path to the JDK install tree (e.g. \fI\,/usr/lib/jvm/java\-7\-openjdk\-amd64\/\fP).
.HP
\fB\-external\-css\fR PATH
.IP
Generate CSS styles file to PATH. This helps to save space when
generating thousands of reports.
.HP
\fB\-external\-js\fR PATH
.IP
Generate JS script file to PATH.
.SS "REPORT:"
.IP
Compatibility report will be generated to:
.IP
compat_reports/LIB_NAME/V1_to_V2/compat_report.html
.SS "EXIT CODES:"
.IP
0 \- Compatible. The tool has run without any errors.
non\-zero \- Incompatible or the tool has run with errors.
.SS "MORE INFORMATION:"
.IP
http://ispras.linuxbase.org/index.php/Java_API_Compliance_Checker
https://github.com/lvc/japi\-compliance\-checker
.SH AUTHOR
Written by Andrey Ponomarenko.
.SH COPYRIGHT
Copyright \(co 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.