linux-kernel - Re: [PATCH] Documentation: kunit: improve example on testing static functions

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CABVgOSnFhWaFmWF19pX4nWng-P3+urYu1OZwnng5z8sdX1rHQw@mail.gmail.com>
Date: Sat, 17 May 2025 17:32:42 +0800
From: David Gow <davidgow@...gle.com>
To: Rae Moar <rmoar@...gle.com>
Cc: brendan.higgins@...ux.dev, skhan@...uxfoundation.org, dlatypov@...gle.com, 
	kunit-dev@...glegroups.com, linux-kernel@...r.kernel.org, 
	linux-kselftest@...r.kernel.org
Subject: Re: [PATCH] Documentation: kunit: improve example on testing static functions

On Sat, 17 May 2025 at 03:06, Rae Moar <rmoar@...gle.com> wrote:
>
> The documentation on testing static functions using the KUnit macros
> VISIBLE_IF_KUNIT and EXPORT_SYMBOL_IF_KUNIT is lacking clarity and
> missing key steps in the example. This has caused bugs and confusion
> among developers.
>
> Improve wording of description and add missing steps to the example.
> This entails adding the "#include <kunit/visibility.h>" line and the
> "MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);" line. Both of which were
> missing from the original example and key to exposing static functions.
>
> Signed-off-by: Rae Moar <rmoar@...gle.com>
> ---

It's always great to have better documentation!

Reviewed-by: David Gow <davidgow@...gle.com>

Thanks,
-- David

>  Documentation/dev-tools/kunit/usage.rst | 38 +++++++++++++++++++------
>  1 file changed, 30 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/dev-tools/kunit/usage.rst b/Documentation/dev-tools/kunit/usage.rst
> index 22955d56b379..038f480074fd 100644
> --- a/Documentation/dev-tools/kunit/usage.rst
> +++ b/Documentation/dev-tools/kunit/usage.rst
> @@ -670,28 +670,50 @@ with ``kunit_remove_action``.
>  Testing Static Functions
>  ------------------------
>
> -If we do not want to expose functions or variables for testing, one option is to
> -conditionally export the used symbol. For example:
> +If you want to test static functions without exposing those functions outside of
> +testing, one option is conditionally export the symbol. When KUnit is enabled,
> +the symbol is exposed but remains static otherwise. To use this method, follow
> +the template below.
>
>  .. code-block:: c
>
> -       /* In my_file.c */
> +       /* In the file containing functions to test "my_file.c" */
>
> -       VISIBLE_IF_KUNIT int do_interesting_thing();
> +       #include <kunit/visibility.h>
> +       #include <my_file.h>
> +       ...
> +       VISIBLE_IF_KUNIT int do_interesting_thing()
> +       {
> +       ...
> +       }
>         EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing);
>
> -       /* In my_file.h */
> +       /* In the header file "my_file.h" */
>
>         #if IS_ENABLED(CONFIG_KUNIT)
>                 int do_interesting_thing(void);
>         #endif
>
> -Alternatively, you could conditionally ``#include`` the test file at the end of
> -your .c file. For example:
> +       /* In the KUnit test file "my_file_test.c" */
> +
> +       #include <kunit/visibility.h>
> +       #include <my_file.h>
> +       ...
> +       MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING);
> +       ...
> +       // Use do_interesting_thing() in tests
> +
> +For a full example, see this `patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_
> +where a test is modified to conditionally expose static functions for testing
> +using the macros above.
> +
> +As an **alternative** to the method above, you could conditionally ``#include``
> +the test file at the end of your .c file. This is not recommended but works
> +if needed. For example:
>
>  .. code-block:: c
>
> -       /* In my_file.c */
> +       /* In "my_file.c" */
>
>         static int do_interesting_thing();
>
>
> base-commit: c2493384e8110d5a4792fff4b9d46e47b78ea10a
> --
> 2.49.0.1101.gccaa498523-goog
>

Download attachment "smime.p7s" of type "application/pkcs7-signature" (5281 bytes)