| Message ID | 20240516112016.309145-2-pvorel@suse.cz |
|---|---|
| State | New |
| Headers | show |
| Series | [1/2] lapi/mount.h: Document reason for not including <linux/mount.h> | expand |
Hi! On 5/16/24 13:20, Petr Vorel wrote: > Convert more C API info (both library and user). > > These info were omitted when converted from GitHub asciidoc wiki format. > > Fixes: 4a72aada8 ("New LTP documentation") > Signed-off-by: Petr Vorel <pvorel@suse.cz> > --- > doc/developers/api_c_tests.rst | 7 +++++ > doc/developers/ltp_library.rst | 47 ++++++++++++++++++++++++++++++++-- > 2 files changed, 52 insertions(+), 2 deletions(-) > > diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst > index ec53ab33c..c7e1a5997 100644 > --- a/doc/developers/api_c_tests.rst > +++ b/doc/developers/api_c_tests.rst > @@ -12,6 +12,13 @@ Core LTP API > .. kernel-doc:: ../../include/tst_res_flags.h > .. kernel-doc:: ../../include/tst_test.h > > +LAPI headers > +------------ > + > +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old > +distributions. LAPI header should always include original header. For more info > +see :doc:`../developers/ltp_library`. > + > Option parsing > -------------- > > diff --git a/doc/developers/ltp_library.rst b/doc/developers/ltp_library.rst > index 723781feb..15dde8e7b 100644 > --- a/doc/developers/ltp_library.rst > +++ b/doc/developers/ltp_library.rst > @@ -9,8 +9,51 @@ General Rules > When we extend library API, we need to apply the same general rules that we use > when writing tests, plus: > > -#. LTP library tests must go inside :master:`lib/newlib_tests` directory > -#. LTP documentation has to be updated according to API changes > +#. LTP library tests must go inside :master:`lib/newlib_tests` directory. > +#. LTP documentation has to be updated according to API changes. > +#. Environment variables should be listed in :doc:`../users/setup_tests`. > + > +C API > +----- > + > +LAPI headers > +~~~~~~~~~~~~ > + > +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old > +distributions. LAPI header should always include original header. Older linux > +headers were problematic, therefore we preferred to use libc headers. There are > +still some bugs when combining certain glibc headers with linux headers, see > +https://sourceware.org/glibc/wiki/Synchronizing_Headers. > + I generally prefer to have a single point where features are documented, otherwise we need to remember to update documentation in two parts instead of one. > +Rules checked with ``make check`` > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +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. > + > +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. > + > +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. > > Shell API > --------- Andrea
> Hi! > On 5/16/24 13:20, Petr Vorel wrote: > > Convert more C API info (both library and user). > > These info were omitted when converted from GitHub asciidoc wiki format. > > Fixes: 4a72aada8 ("New LTP documentation") > > Signed-off-by: Petr Vorel <pvorel@suse.cz> > > --- > > doc/developers/api_c_tests.rst | 7 +++++ > > doc/developers/ltp_library.rst | 47 ++++++++++++++++++++++++++++++++-- > > 2 files changed, 52 insertions(+), 2 deletions(-) > > diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst > > index ec53ab33c..c7e1a5997 100644 > > --- a/doc/developers/api_c_tests.rst > > +++ b/doc/developers/api_c_tests.rst > > @@ -12,6 +12,13 @@ Core LTP API > > .. kernel-doc:: ../../include/tst_res_flags.h > > .. kernel-doc:: ../../include/tst_test.h > > +LAPI headers > > +------------ > > + > > +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old > > +distributions. LAPI header should always include original header. For more info > > +see :doc:`../developers/ltp_library`. > > + > > Option parsing > > -------------- > > diff --git a/doc/developers/ltp_library.rst b/doc/developers/ltp_library.rst > > index 723781feb..15dde8e7b 100644 > > --- a/doc/developers/ltp_library.rst > > +++ b/doc/developers/ltp_library.rst > > @@ -9,8 +9,51 @@ General Rules > > When we extend library API, we need to apply the same general rules that we use > > when writing tests, plus: > > -#. LTP library tests must go inside :master:`lib/newlib_tests` directory > > -#. LTP documentation has to be updated according to API changes > > +#. LTP library tests must go inside :master:`lib/newlib_tests` directory. > > +#. LTP documentation has to be updated according to API changes. > > +#. Environment variables should be listed in :doc:`../users/setup_tests`. > > + > > +C API > > +----- > > + > > +LAPI headers > > +~~~~~~~~~~~~ > > + > > +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old > > +distributions. LAPI header should always include original header. Older linux > > +headers were problematic, therefore we preferred to use libc headers. There are > > +still some bugs when combining certain glibc headers with linux headers, see > > +https://sourceware.org/glibc/wiki/Synchronizing_Headers. > > + > I generally prefer to have a single point where features are documented, > otherwise we need to remember > to update documentation in two parts instead of one. Yes, that's preferred. But in many parts of the docs there is some info for developing new tests and other for developing library. Sometimes even third place: "maintainer checklist". Kind regards, Petr > > +Rules checked with ``make check`` > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +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. > > + > > +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. > > + > > +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. > > Shell API > > --------- > Andrea
diff --git a/doc/developers/api_c_tests.rst b/doc/developers/api_c_tests.rst index ec53ab33c..c7e1a5997 100644 --- a/doc/developers/api_c_tests.rst +++ b/doc/developers/api_c_tests.rst @@ -12,6 +12,13 @@ Core LTP API .. kernel-doc:: ../../include/tst_res_flags.h .. kernel-doc:: ../../include/tst_test.h +LAPI headers +------------ + +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old +distributions. LAPI header should always include original header. For more info +see :doc:`../developers/ltp_library`. + Option parsing -------------- diff --git a/doc/developers/ltp_library.rst b/doc/developers/ltp_library.rst index 723781feb..15dde8e7b 100644 --- a/doc/developers/ltp_library.rst +++ b/doc/developers/ltp_library.rst @@ -9,8 +9,51 @@ General Rules When we extend library API, we need to apply the same general rules that we use when writing tests, plus: -#. LTP library tests must go inside :master:`lib/newlib_tests` directory -#. LTP documentation has to be updated according to API changes +#. LTP library tests must go inside :master:`lib/newlib_tests` directory. +#. LTP documentation has to be updated according to API changes. +#. Environment variables should be listed in :doc:`../users/setup_tests`. + +C API +----- + +LAPI headers +~~~~~~~~~~~~ + +Use our LAPI headers (``include "lapi/foo.h"``) to keep compatibility with old +distributions. LAPI header should always include original header. Older linux +headers were problematic, therefore we preferred to use libc headers. There are +still some bugs when combining certain glibc headers with linux headers, see +https://sourceware.org/glibc/wiki/Synchronizing_Headers. + +Rules checked with ``make check`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +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. + +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. Shell API ---------
Convert more C API info (both library and user). These info were omitted when converted from GitHub asciidoc wiki format. Fixes: 4a72aada8 ("New LTP documentation") Signed-off-by: Petr Vorel <pvorel@suse.cz> --- doc/developers/api_c_tests.rst | 7 +++++ doc/developers/ltp_library.rst | 47 ++++++++++++++++++++++++++++++++-- 2 files changed, 52 insertions(+), 2 deletions(-)