1f08c3bdfSopenharmony_ciLTP Library API Writing Guidelines 2f08c3bdfSopenharmony_ci================================== 3f08c3bdfSopenharmony_ci 4f08c3bdfSopenharmony_ciNOTE: See also 5f08c3bdfSopenharmony_ci https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines], 6f08c3bdfSopenharmony_ci https://github.com/linux-test-project/ltp/wiki/C-Test-API[C Test API], 7f08c3bdfSopenharmony_ci https://github.com/linux-test-project/ltp/wiki/Shell-Test-API[Shell Test API]. 8f08c3bdfSopenharmony_ci 9f08c3bdfSopenharmony_ci1. General Rules 10f08c3bdfSopenharmony_ci---------------- 11f08c3bdfSopenharmony_ci 12f08c3bdfSopenharmony_ciFor extending library API it applies the same general rules as for writing tests, 13f08c3bdfSopenharmony_ci(see https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines[Test Writing Guidelines], 14f08c3bdfSopenharmony_cioffline: 'doc/test-writing-guidelines.txt'), 15f08c3bdfSopenharmony_ciwith strong focus on readability and simplicity. 16f08c3bdfSopenharmony_ci 17f08c3bdfSopenharmony_ciLibrary tests are in 'lib/newlib_tests' directory. 18f08c3bdfSopenharmony_ci 19f08c3bdfSopenharmony_ciDon't forget to update docs when you change the API. 20f08c3bdfSopenharmony_ci 21f08c3bdfSopenharmony_ci2. C API 22f08c3bdfSopenharmony_ci-------- 23f08c3bdfSopenharmony_ci 24f08c3bdfSopenharmony_ci2.1 LTP-001: Sources have tst_ prefix 25f08c3bdfSopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 26f08c3bdfSopenharmony_ci 27f08c3bdfSopenharmony_ciAPI source code is in headers `include/*.h`, `include/lapi/*.h` (backward 28f08c3bdfSopenharmony_cicompatibility for old kernel and libc) and C sources in `lib/*.c`. Files have 29f08c3bdfSopenharmony_ci'tst_' prefix. 30f08c3bdfSopenharmony_ci 31f08c3bdfSopenharmony_ci2.2 LTP-002: TST_RET and TST_ERR are not modified 32f08c3bdfSopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33f08c3bdfSopenharmony_ci 34f08c3bdfSopenharmony_ciThe test author is guaranteed that the test API will not modify these 35f08c3bdfSopenharmony_civariables. This prevents silent errors where the return value and 36f08c3bdfSopenharmony_cierrno are overwritten before the test has chance to check them. 37f08c3bdfSopenharmony_ci 38f08c3bdfSopenharmony_ciThe macros which are clearly intended to update these variables. That 39f08c3bdfSopenharmony_ciis +TEST+ and those in 'tst_test_macros.h'. Are of course allowed to 40f08c3bdfSopenharmony_ciupdate these variables. 41f08c3bdfSopenharmony_ci 42f08c3bdfSopenharmony_ci2.3 LTP-003: Externally visible library symbols have the tst_ prefix 43f08c3bdfSopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44f08c3bdfSopenharmony_ci 45f08c3bdfSopenharmony_ciFunctions, types and variables in the public test API should have the 46f08c3bdfSopenharmony_citst_ prefix. With some exceptions for symbols already prefixed with 47f08c3bdfSopenharmony_cisafe_ or ltp_. 48f08c3bdfSopenharmony_ci 49f08c3bdfSopenharmony_ciStatic (private) symbols should not have the prefix. 50f08c3bdfSopenharmony_ci 51f08c3bdfSopenharmony_ci 52f08c3bdfSopenharmony_ci3. Shell API 53f08c3bdfSopenharmony_ci------------ 54f08c3bdfSopenharmony_ci 55f08c3bdfSopenharmony_ciAPI source code is in `tst_test.sh`, `tst_security.sh` and `tst_net.sh` 56f08c3bdfSopenharmony_ci(all in 'testcases/lib' directory). 57f08c3bdfSopenharmony_ci 58f08c3bdfSopenharmony_ciChanges in the shell API should not introduce uncommon dependencies 59f08c3bdfSopenharmony_ci(use basic commands installed everywhere by default). 60