85 lines
3.0 KiB
Plaintext
85 lines
3.0 KiB
Plaintext
|
LTP Library API Writing Guidelines
|
||
|
|
==================================
|
||
|
|
|
||
|
|
NOTE: See also
|
||
|
|
https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines],
|
||
|
|
https://github.com/linux-test-project/ltp/wiki/C-Test-API[C Test API],
|
||
|
|
https://github.com/linux-test-project/ltp/wiki/Shell-Test-API[Shell Test API].
|
||
|
|
|
||
|
|
1. General Rules
|
||
|
|
----------------
|
||
|
|
|
||
|
|
For extending library API it applies the same general rules as for writing tests,
|
||
|
|
(see https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines],
|
||
|
|
offline: 'doc/test-writing-guidelines.txt'),
|
||
|
|
with strong focus on readability and simplicity.
|
||
|
|
|
||
|
|
Library tests are in 'lib/newlib_tests' directory.
|
||
|
|
|
||
|
|
Don't forget to update docs when you change the API.
|
||
|
|
|
||
|
|
Environment variables should be listed in
|
||
|
|
https://github.com/linux-test-project/ltp/wiki/User-Guidelines[LTP User Guidelines]
|
||
|
|
and in help output (`-h`) for both C and shell API.
|
||
|
|
|
||
|
|
2. C API
|
||
|
|
--------
|
||
|
|
|
||
|
|
2.1 LTP-001: Sources have tst_ prefix
|
||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
API source code is in headers in 'include/{empty}*.h', 'include/lapi/{empty}*.h'
|
||
|
|
(backward compatibility for old kernel and libc) and C sources in 'lib/{empty}*.c'.
|
||
|
|
Files have `tst_` prefix.
|
||
|
|
|
||
|
|
2.2 LTP-002: TST_RET and TST_ERR are not modified
|
||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
The test author is guaranteed that the test API will not modify these
|
||
|
|
variables. This prevents silent errors where the return value and
|
||
|
|
errno are overwritten before the test has chance to check them.
|
||
|
|
|
||
|
|
The macros which are clearly intended to update these variables. That
|
||
|
|
is `TEST` and those in 'tst_test_macros.h'. Are of course allowed to
|
||
|
|
update these variables.
|
||
|
|
|
||
|
|
2.3 LTP-003: Externally visible library symbols have the tst_ prefix
|
||
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
Functions, types and variables in the public test API should have the
|
||
|
|
tst_ prefix. With some exceptions for symbols already prefixed with
|
||
|
|
`safe_` or `ltp_`.
|
||
|
|
|
||
|
|
Static (private) symbols should not have the prefix.
|
||
|
|
|
||
|
|
|
||
|
|
3. Shell API
|
||
|
|
------------
|
||
|
|
|
||
|
|
API source code is in 'tst_test.sh', 'tst_security.sh' and 'tst_net.sh'
|
||
|
|
(all in 'testcases/lib' directory).
|
||
|
|
|
||
|
|
Changes in the shell API should not introduce uncommon dependencies
|
||
|
|
(use basic commands installed everywhere by default).
|
||
|
|
|
||
|
|
3.1 Shell libraries
|
||
|
|
~~~~~~~~~~~~~~~~~~~
|
||
|
|
|
||
|
|
Aside from shell API libraries in 'testcases/lib', it's worth putting
|
||
|
|
common code for a group of tests into a shell library. The filename
|
||
|
|
should end with '_lib.sh' and the library should load 'tst_test.sh' or
|
||
|
|
'tst_net.sh'.
|
||
|
|
|
||
|
|
Shell libraries should have conditional expansion for 'TST_SETUP' or 'TST_CLEANUP',
|
||
|
|
to avoid surprises when test specific setup/cleanup function is redefined by
|
||
|
|
shell library.
|
||
|
|
|
||
|
|
[source,sh]
|
||
|
|
-------------------------------------------------------------------------------
|
||
|
|
# ipsec_lib.sh
|
||
|
|
# SPDX-License-Identifier: GPL-2.0-or-later
|
||
|
|
TST_SETUP="${TST_SETUP:-ipsec_lib_setup}"
|
||
|
|
...
|
||
|
|
. tst_test.sh
|
||
|
|
-------------------------------------------------------------------------------
|