1LTP Library API Writing Guidelines 2================================== 3 4NOTE: See also 5 https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines], 6 https://github.com/linux-test-project/ltp/wiki/C-Test-API[C Test API], 7 https://github.com/linux-test-project/ltp/wiki/Shell-Test-API[Shell Test API]. 8 91. General Rules 10---------------- 11 12For extending library API it applies the same general rules as for writing tests, 13(see https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines], 14offline: 'doc/test-writing-guidelines.txt'), 15with strong focus on readability and simplicity. 16 17Library tests are in 'lib/newlib_tests' directory. 18 19Don't forget to update docs when you change the API. 20 21Environment variables should be listed in 22https://github.com/linux-test-project/ltp/wiki/User-Guidelines[LTP User Guidelines] 23and in help output (`-h`) for both C and shell API. 24 252. C API 26-------- 27 282.1 LTP-001: Sources have tst_ prefix 29~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 30 31API source code is in headers in 'include/{empty}*.h', 'include/lapi/{empty}*.h' 32(backward compatibility for old kernel and libc) and C sources in 'lib/{empty}*.c'. 33Files have `tst_` prefix. 34 352.2 LTP-002: TST_RET and TST_ERR are not modified 36~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 37 38The test author is guaranteed that the test API will not modify these 39variables. This prevents silent errors where the return value and 40errno are overwritten before the test has chance to check them. 41 42The macros which are clearly intended to update these variables. That 43is `TEST` and those in 'tst_test_macros.h'. Are of course allowed to 44update these variables. 45 462.3 LTP-003: Externally visible library symbols have the tst_ prefix 47~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 48 49Functions, types and variables in the public test API should have the 50tst_ prefix. With some exceptions for symbols already prefixed with 51`safe_` or `ltp_`. 52 53Static (private) symbols should not have the prefix. 54 55 563. Shell API 57------------ 58 59API source code is in 'tst_test.sh', 'tst_security.sh' and 'tst_net.sh' 60(all in 'testcases/lib' directory). 61 62Changes in the shell API should not introduce uncommon dependencies 63(use basic commands installed everywhere by default). 64 653.1 Shell libraries 66~~~~~~~~~~~~~~~~~~~ 67 68Aside from shell API libraries in 'testcases/lib', it's worth putting 69common code for a group of tests into a shell library. The filename 70should end with '_lib.sh' and the library should load 'tst_test.sh' or 71'tst_net.sh'. 72 73Shell libraries should have conditional expansion for 'TST_SETUP' or 'TST_CLEANUP', 74to avoid surprises when test specific setup/cleanup function is redefined by 75shell library. 76 77[source,sh] 78------------------------------------------------------------------------------- 79# ipsec_lib.sh 80# SPDX-License-Identifier: GPL-2.0-or-later 81TST_SETUP="${TST_SETUP:-ipsec_lib_setup}" 82... 83. tst_test.sh 84------------------------------------------------------------------------------- 85