.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
.TH API-SANITY-CHECKER "1" "July 2016" "api-sanity-checker Sanity Checker 1.98.7" "User Commands"
.SH NAME
api-sanity-checker \- an automatic generator of basic unit tests for a C/C++ library API.
.SH DESCRIPTION
.SS "NAME:"
.IP
API Sanity Checker (api\-sanity\-checker)
Generate basic unit tests for a C/C++ library API
.SS "DESCRIPTION:"
.IP
API Sanity Checker is an automatic generator of basic unit tests for a C/C++
library. It helps to quickly generate simple ("sanity" or "shallow"
quality) tests for every function in an API using their signatures, data type
definitions and relationships between functions straight from the library
header files ("Header\-Driven Generation"). Each test case contains a function
call with reasonable (in most, but unfortunately not all, cases) input
parameters. The quality of generated tests allows one to check absence of critical
errors in simple use cases and can be greatly improved by involving of highly
reusable specialized types for the library.
.IP
The tool can execute generated tests and detect crashes, aborts, all kinds of
emitted signals, non\-zero program return code, program hanging and requirement
failures (if specified). The tool can be considered as a tool for out\-of\-box
low\-cost sanity checking of library API or as a test development framework for
initial generation of templates for advanced tests. Also it supports universal
Template2Code format of tests, splint specifications, random test generation
mode and other useful features.
.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
api\-sanity\-checker [options]
.SS "EXAMPLE:"
.IP
api\-sanity\-checker \fB\-lib\fR NAME \fB\-d\fR VER.xml \fB\-gen\fR \fB\-build\fR \fB\-run\fR
.IP
VERSION.xml is XML\-descriptor:
.IP
<version>
.IP
1.0
.IP
</version>
.IP
<headers>
.IP
/path1/to/header(s)/
/path2/to/header(s)/
.IP
\&...
.IP
</headers>
.IP
<libs>
.IP
/path1/to/library(ies)/
/path2/to/library(ies)/
.IP
\&...
.IP
</libs>
.SS "INFORMATION OPTIONS:"
.HP
\fB\-h\fR|\-help
.IP
Print this help.
.HP
\fB\-info\fR
.IP
Print complete info.
.HP
\fB\-v\fR|\-version
.IP
Print version information.
.HP
\fB\-dumpversion\fR
.IP
Print the tool version (1.98.7) and don't do anything else.
.SS "GENERAL OPTIONS:"
.HP
\fB\-l\fR|\-lib|\-library NAME
.IP
Library name (without version).
.HP
\fB\-d\fR|\-descriptor PATH
.IP
Path to the library descriptor (VER.xml file):
.IP
<version>
.IP
1.0
.IP
</version>
.IP
<headers>
.IP
/path1/to/header(s)/
/path2/to/header(s)/
\&...
.IP
</headers>
.IP
<libs>
.IP
/path1/to/library(ies)/
/path2/to/library(ies)/
\&...
.IP
</libs>
.IP
For more information, please see:
.IP
http://lvc.github.com/api\-sanity\-checker/Xml\-Descriptor.html
.HP
\fB\-gen\fR|\-generate
.IP
Generate test(s). Options \fB\-l\fR and \fB\-d\fR should be specified.
To generate test for the particular function use it with \fB\-f\fR option.
Exit code: number of test cases failed to build.
.HP
\fB\-build\fR|\-make
.IP
Build test(s). Options \fB\-l\fR and \fB\-d\fR should be specified.
To build test for the particular function use it with \fB\-f\fR option.
Exit code: number of test cases failed to generate.
.HP
\fB\-run\fR
.IP
Run test(s), create test report. Options \fB\-l\fR and \fB\-d\fR should be specified.
To run test for the particular function use it with \fB\-f\fR option.
Exit code: number of failed test cases.
.HP
\fB\-clean\fR
.IP
Clean test(s). Options \fB\-l\fR and \fB\-d\fR should be specified.
To clean test for the particular function use it with \fB\-f\fR option.
.SS "EXTRA OPTIONS:"
.HP
\fB\-vnum\fR NUM
.IP
Specify library version outside the descriptor.
.HP
\fB\-s\fR|\-symbol NAME
.IP
Generate/Build/Run test for the specified function
(mangled name in C++).
.HP
\fB\-symbols\-list\fR PATH
.IP
This option allows one to specify a file with a list of functions
(one per line, mangled name in C++) that should be tested,
other library functions will not be tested.
.HP
\fB\-header\fR NAME
.IP
This option allows one to restrict a list of functions that should be tested
by providing a header file name in which they are declared. This option
is intended for step\-by\-step tests development.
.HP
\fB\-all\fR
.IP
Generate tests for all symbols recursively included
in header file(s).
.HP
\fB\-xvfb\fR
.IP
Use Xvfb\-server instead of current X\-server (default)
for running tests.
.HP
\fB\-t2c\fR|\-template2code
.IP
Generate tests in the universal Template2Code format.
For more information, please see:
.IP
http://sourceforge.net/projects/template2code/
.HP
\fB\-strict\-gen\fR
.IP
Terminate the process of generating tests and return
error code '1' if cannot generate at least one test case.
.HP
\fB\-strict\-build\fR
.IP
Terminate the process of building tesst and return
error code '1' if cannot build at least one test case.
.HP
\fB\-strict\-run\fR
.IP
Terminate the process of running tests and return
error code '1' if at least one test case failed.
.HP
\fB\-strict\fR
.IP
This option enables all \fB\-strict\-\fR* options.
.HP
\fB\-r\fR|\-random
.IP
Random test generation mode.
.HP
\fB\-min\fR
.IP
Generate minimun code, call functions with minimum number of parameters
to initialize parameters of other functions.
.HP
\fB\-max\fR
.IP
Generate maximum code, call functions with maximum number of parameters
to initialize parameters of other functions.
.HP
\fB\-show\-retval\fR
.IP
Show the function return type in the report.
.HP
\fB\-check\-retval\fR
.IP
Insert requirements on return values (retval!=NULL) for each
called function.
.HP
\fB\-st\fR|\-specialized\-types PATH
.IP
Path to the file with the collection of specialized types.
For more information, please see:
.IP
http://lvc.github.com/api\-sanity\-checker/Specialized\-Type.html
.HP
\fB\-td\fR|\-test\-data PATH
.IP
Path to the directory with the test data files.
For more information, please see:
.IP
http://lvc.github.com/api\-sanity\-checker/Specialized\-Type.html
.HP
\fB\-headers\-only\fR
.IP
If the library consists of inline functions only and has no shared
objects then you should specify this option.
.HP
\fB\-no\-inline\fR
.IP
Don't generate tests for inline functions.
.HP
\fB\-keep\-internal\fR
.IP
Generate tests for internal symbols (functions with '__' prefix and
methods of classes declared inside other classes).
.HP
\fB\-isolated\fR
.IP
Allow one to restrict functions usage by the lists specified by the
\fB\-functions\-list\fR option or by the group devision in the descriptor.
.HP
\fB\-view\-only\fR
.IP
Remove all files from the test suite except *.html files. This option
allows one to create a lightweight html\-index for all tests.
.HP
\fB\-disable\-default\-values\fR
.IP
Disable usage of default values for function parameters.
.HP
\fB\-optimize\-includes\fR LEVEL
.IP
Enable optimization of the list of included headers in each test case.
Available levels:
.IP
High (default)
Medium
Low
None \- disable
.HP
\fB\-p\fR|\-params PATH
.IP
Path to file with the function parameter names. It can be used for
improving generated tests if the library header files don't contain
parameter names. File format:
.IP
func1;param1;param2;param3 ...
func2;param1;param2;param3 ...
\&...
.HP
\fB\-title\fR NAME
.IP
The name of the library in the report title.
.HP
\fB\-relpath\fR|\-reldir PATH
.IP
Replace {RELPATH} in the library descriptor by PATH.
.HP
\fB\-lang\fR LANG
.IP
Set library language (C or C++). You can use this option if the tool
cannot auto\-detect a language.
.HP
\fB\-target\fR COMPILER
.IP
The compiler that should be used to build generated tests under Windows.
Supported:
.IP
gcc \- GNU compiler
cl \- MS compiler (default)
.HP
\fB\-debug\fR
.IP
Write extended log for debugging.
.HP
\fB\-cache\fR
.IP
Cache the ABI dump and use it on the next run.
.SS "OTHER OPTIONS:"
.HP
\fB\-test\fR
.IP
Run internal tests. Create a simple library and run the tool on it.
This option allows one to check if the tool works correctly on the system.
.HP
\fB\-disable\-variable\-reuse\fR
.IP
Disable reusing of previously created variables in the test.
.HP
\fB\-long\-variable\-names\fR
.IP
Enable long (complex) variable names instead of short names.
.SS "EXIT CODES:"
.IP
0 \- Successful tests. The tool has run without any errors.
non\-zero \- Tests failed or the tool has run with errors.
.SS "MORE INFORMATION:"
.IP
http://lvc.github.com/api\-sanity\-checker/
.SH AUTHOR
This manual page was written by Mathieu Malaterre <malat@debian.org> for the
Debian GNU/Linux system (but may be used by others).
.PP
Written by Andrey Ponomarenko.
.SH COPYRIGHT
Copyright \(co 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.