Skip to content

LTP Library API Writing Guidelines

Wiki mirror edited this page Oct 6, 2023 · 13 revisions

LTP Library API Writing Guidelines

1. General Rules

For extending library API it applies the same general rules as for writing tests, (see Test Writing Guidelines, offline: doc/Test-Writing-Guidelines.asciidoc), 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 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/*.h, include/lapi/*.h (backward compatibility for old kernel and libc) and C sources in lib/*.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.

# ipsec_lib.sh
# SPDX-License-Identifier: GPL-2.0-or-later
TST_SETUP="${TST_SETUP:-ipsec_lib_setup}"
...
. tst_test.sh