[LTP] [PATCH 1/2] lapi/mount.h: Document reason for not including <linux/mount.h>

[LTP] [PATCH 1/2] lapi/mount.h: Document reason for not including <linux/mount.h>

[Petr Vorel]

Signed-off-by: Petr Vorel <pvorel@suse.cz>
---
 include/lapi/mount.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/include/lapi/mount.h b/include/lapi/mount.h
index c1af944fe..e3e639965 100644
--- a/include/lapi/mount.h
+++ b/include/lapi/mount.h
@@ -1,12 +1,16 @@
 // SPDX-License-Identifier: GPL-2.0-or-later
 /*
- * Copyright (c) Linux Test Project, 2015-2022
+ * Copyright (c) Linux Test Project, 2015-2024
  * Copyright (c) 2015 Cui Bixuan <cuibixuan@huawei.com>
  */
 
 #ifndef LAPI_MOUNT_H__
 #define LAPI_MOUNT_H__
 
+/*
+ * NOTE: <sys/mount.h> conflicts with <linux/mount.h>, therefore not added
+ * although some defintions from it are used.
+ */
 #include <sys/mount.h>
 
 #ifndef MS_REC
-- 
2.43.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

[LTP] [PATCH 2/2] doc: Convert more C API info

[Petr Vorel]

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.
+
+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
 ---------
-- 
2.43.0


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 2/2] doc: Convert more C API info

[Andrea Cervesato via ltp]

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


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 2/2] doc: Convert more C API info

[Petr Vorel]

> 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


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 2/2] doc: Convert more C API info

[Andrea Cervesato via ltp]

Hi Petr,

sorry for the delay. Feel free to push this patch.

Acked-by: Andrea Cervesato <andrea.cervesato@suse.com>

On 5/16/24 16:43, Petr Vorel wrote:
> 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
Andrea

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp

Re: [LTP] [PATCH 1/2] lapi/mount.h: Document reason for not including <linux/mount.h>

[Andrea Cervesato via ltp]

Hi!

Reviewed-by: Andrea Cervesato <andrea.cervesato@suse.com>

On 5/16/24 13:20, Petr Vorel wrote:
> Signed-off-by: Petr Vorel <pvorel@suse.cz>
> ---
>   include/lapi/mount.h | 6 +++++-
>   1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/include/lapi/mount.h b/include/lapi/mount.h
> index c1af944fe..e3e639965 100644
> --- a/include/lapi/mount.h
> +++ b/include/lapi/mount.h
> @@ -1,12 +1,16 @@
>   // SPDX-License-Identifier: GPL-2.0-or-later
>   /*
> - * Copyright (c) Linux Test Project, 2015-2022
> + * Copyright (c) Linux Test Project, 2015-2024
>    * Copyright (c) 2015 Cui Bixuan <cuibixuan@huawei.com>
>    */
>   
>   #ifndef LAPI_MOUNT_H__
>   #define LAPI_MOUNT_H__
>   
> +/*
> + * NOTE: <sys/mount.h> conflicts with <linux/mount.h>, therefore not added
> + * although some defintions from it are used.
> + */
>   #include <sys/mount.h>
>   
>   #ifndef MS_REC

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp