api-sanity-checker(1)

1API(1)                           User Commands                          API(1)
2
3
4
5   NAME:
6              API  Sanity  Checker  (api-sanity-checker)  Generate  basic unit
7              tests for a C/C++ library API
8
9   DESCRIPTION:
10              API Sanity Checker is an automatic generator of basic unit tests
11              for  a C/C++ library. It helps to quickly generate simple ("san‐
12              ity" or "shallow" quality) tests for every function  in  an  API
13              using  their signatures, data type definitions and relationships
14              between  functions  straight  from  the  library  header   files
15              ("Header-Driven Generation"). Each test case contains a function
16              call with reasonable (in most, but unfortunately not all, cases)
17              input parameters. The quality of generated tests allows to check
18              absence of critical errors  in  simple  use  cases  and  can  be
19              greatly  improved  by  involving  of highly reusable specialized
20              types for the library.
21
22              The tool can execute generated tests and detect crashes, aborts,
23              all kinds of emitted signals, non-zero program return code, pro‐
24              gram hanging and requirement failures (if specified).  The  tool
25              can  be  considered  as  a  tool  for out-of-box low-cost sanity
26              checking of library API or as a test development  framework  for
27              initial generation of templates for advanced tests. Also it sup‐
28              ports universal Template2Code format of tests, splint specifica‐
29              tions, random test generation mode and other useful features.
30
31              This  tool is free software: you can redistribute it and/or mod‐
32              ify it under the terms of the GNU LGPL or GNU GPL.
33
34   USAGE:
35              api-sanity-checker [options]
36
37   EXAMPLE:
38              api-sanity-checker -lib NAME -d VER.xml -gen -build -run
39
40              VERSION.xml is XML-descriptor:
41
42              <version>
43
44              1.0
45
46              </version>
47
48              <headers>
49
50              /path1/to/header(s)/ /path2/to/header(s)/
51
52              ...
53
54              </headers>
55
56              <libs>
57
58              /path1/to/library(ies)/ /path2/to/library(ies)/
59
60              ...
61
62              </libs>
63
64   INFORMATION OPTIONS:
65       -h|-help
66
67              Print this help.
68
69       -info
70
71              Print complete info.
72
73       -v|-version
74
75              Print version information.
76
77       -dumpversion
78
79              Print the tool version (1.98.7) and don't do anything else.
80
81   GENERAL OPTIONS:
82       -l|-lib|-library NAME
83
84              Library name (without version).
85
86       -d|-descriptor PATH
87
88              Path to the library descriptor (VER.xml file):
89
90              <version>
91
92              1.0
93
94              </version>
95
96              <headers>
97
98              /path1/to/header(s)/ /path2/to/header(s)/ ...
99
100              </headers>
101
102              <libs>
103
104              /path1/to/library(ies)/ /path2/to/library(ies)/ ...
105
106              </libs>
107
108              For more information, please see:
109
110              http://lvc.github.com/api-sanity-checker/Xml-Descriptor.html
111
112       -gen|-generate
113
114              Generate test(s). Options -l and -d  should  be  specified.   To
115              generate test for the particular function use it with -f option.
116              Exit code: number of test cases failed to build.
117
118       -build|-make
119
120              Build test(s). Options -l and -d should be specified.  To  build
121              test  for  the  particular function use it with -f option.  Exit
122              code: number of test cases failed to generate.
123
124       -run
125
126              Run test(s), create test report. Options -l  and  -d  should  be
127              specified.   To run test for the particular function use it with
128              -f option.  Exit code: number of failed test cases.
129
130       -clean
131
132              Clean test(s). Options -l and -d should be specified.  To  clean
133              test for the particular function use it with -f option.
134
135   EXTRA OPTIONS:
136       -vnum NUM
137
138              Specify library version outside the descriptor.
139
140       -s|-symbol NAME
141
142              Generate/Build/Run test for the specified function (mangled name
143              in C++).
144
145       -symbols-list PATH
146
147              This option allows to specify a file with a  list  of  functions
148              (one per line, mangled name in C++) that should be tested, other
149              library functions will not be tested.
150
151       -header NAME
152
153              This option allows to restrict a list of functions  that  should
154              be  tested by providing a header file name in which they are de‐
155              clared. This option is intended for step-by-step tests  develop‐
156              ment.
157
158       -all
159
160              Generate  tests  for  all symbols recursively included in header
161              file(s).
162
163       -xvfb
164
165              Use Xvfb-server instead of current X-server (default)  for  run‐
166              ning tests.
167
168       -t2c|-template2code
169
170              Generate  tests in the universal Template2Code format.  For more
171              information, please see:
172
173              http://sourceforge.net/projects/template2code/
174
175       -strict-gen
176
177              Terminate the process of generating tests and return error  code
178              '1' if cannot generate at least one test case.
179
180       -strict-build
181
182              Terminate  the  process  of building tesst and return error code
183              '1' if cannot build at least one test case.
184
185       -strict-run
186
187              Terminate the process of running tests and return error code '1'
188              if at least one test case failed.
189
190       -strict
191
192              This option enables all -strict-* options.
193
194       -r|-random
195
196              Random test generation mode.
197
198       -min
199
200              Generate minimun code, call functions with minimum number of pa‐
201              rameters to initialize parameters of other functions.
202
203       -max
204
205              Generate maximum code, call functions with maximum number of pa‐
206              rameters to initialize parameters of other functions.
207
208       -show-retval
209
210              Show the function return type in the report.
211
212       -check-retval
213
214              Insert  requirements  on  return  values (retval!=NULL) for each
215              called function.
216
217       -st|-specialized-types PATH
218
219              Path to the file with the collection of specialized types.   For
220              more information, please see:
221
222              http://lvc.github.com/api-sanity-checker/Specialized-Type.html
223
224       -td|-test-data PATH
225
226              Path to the directory with the test data files.  For more infor‐
227              mation, please see:
228
229              http://lvc.github.com/api-sanity-checker/Specialized-Type.html
230
231       -headers-only
232
233              If the library consists of inline  functions  only  and  has  no
234              shared objects then you should specify this option.
235
236       -no-inline
237
238              Don't generate tests for inline functions.
239
240       -keep-internal
241
242              Generate  tests for internal symbols (functions with '__' prefix
243              and methods of classes declared inside other classes).
244
245       -isolated
246
247              Allow to restrict functions usage by the lists specified by  the
248              -functions-list  option or by the group devision in the descrip‐
249              tor.
250
251       -view-only
252
253              Remove all files from the test suite except *.html  files.  This
254              option allows to create a lightweight html-index for all tests.
255
256       -disable-default-values
257
258              Disable usage of default values for function parameters.
259
260       -optimize-includes LEVEL
261
262              Enable optimization of the list of included headers in each test
263              case.  Available levels:
264
265              High (default) Medium Low None - disable
266
267       -p|-params PATH
268
269              Path to file with the function parameter names. It can  be  used
270              for  improving generated tests if the library header files don't
271              contain parameter names. File format:
272
273              func1;param1;param2;param3 ...   func2;param1;param2;param3  ...
274              ...
275
276       -title NAME
277
278              The name of the library in the report title.
279
280       -relpath|-reldir PATH
281
282              Replace {RELPATH} in the library descriptor by PATH.
283
284       -lang LANG
285
286              Set  library language (C or C++). You can use this option if the
287              tool cannot auto-detect a language.
288
289       -target COMPILER
290
291              The compiler that should be used to build generated tests  under
292              Windows.  Supported:
293
294              gcc - GNU compiler cl - MS compiler (default)
295
296       -debug
297
298              Write extended log for debugging.
299
300       -cache
301
302              Cache the ABI dump and use it on the next run.
303
304   OTHER OPTIONS:
305       -test
306
307              Run  internal tests. Create a simple library and run the tool on
308              it.  This option allows to check if the tool works correctly  on
309              the system.
310
311       -disable-variable-reuse
312
313              Disable reusing of previously created variables in the test.
314
315       -long-variable-names
316
317              Enable long (complex) variable names instead of short names.
318
319   EXIT CODES:
320              0  -  Successful  tests.  The  tool  has run without any errors.
321              non-zero - Tests failed or the tool has run with errors.
322
323   MORE INFORMATION:
324              http://lvc.github.com/api-sanity-checker/
325

AUTHOR

327       Written by Andrey Ponomarenko.
328

COPYRIGHT

330       Copyright © 2015 Andrey Ponomarenko's ABI Laboratory License:  LGPL  or
331       GPL  <http://www.gnu.org/licenses/>  This program is free software: you
332       can redistribute it and/or modify it.
333
334
335
336API Sanity Checker 1.98.7        January 2022                           API(1)