Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

Documentation: kunit: improve example on testing static functions

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.

Link: https://lore.kernel.org/r/20250516190631.1214081-1-rmoar@google.com
Signed-off-by: Rae Moar <rmoar@google.com>
Reviewed-by: David Gow <davidgow@google.com>
Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>

authored by

Rae Moar and committed by
Shuah Khan
d208025d c2493384

+30 -8
+30 -8
Documentation/dev-tools/kunit/usage.rst
··· 670 670 Testing Static Functions 671 671 ------------------------ 672 672 673 - If we do not want to expose functions or variables for testing, one option is to 674 - conditionally export the used symbol. For example: 673 + If you want to test static functions without exposing those functions outside of 674 + testing, one option is conditionally export the symbol. When KUnit is enabled, 675 + the symbol is exposed but remains static otherwise. To use this method, follow 676 + the template below. 675 677 676 678 .. code-block:: c 677 679 678 - /* In my_file.c */ 680 + /* In the file containing functions to test "my_file.c" */ 679 681 680 - VISIBLE_IF_KUNIT int do_interesting_thing(); 682 + #include <kunit/visibility.h> 683 + #include <my_file.h> 684 + ... 685 + VISIBLE_IF_KUNIT int do_interesting_thing() 686 + { 687 + ... 688 + } 681 689 EXPORT_SYMBOL_IF_KUNIT(do_interesting_thing); 682 690 683 - /* In my_file.h */ 691 + /* In the header file "my_file.h" */ 684 692 685 693 #if IS_ENABLED(CONFIG_KUNIT) 686 694 int do_interesting_thing(void); 687 695 #endif 688 696 689 - Alternatively, you could conditionally ``#include`` the test file at the end of 690 - your .c file. For example: 697 + /* In the KUnit test file "my_file_test.c" */ 698 + 699 + #include <kunit/visibility.h> 700 + #include <my_file.h> 701 + ... 702 + MODULE_IMPORT_NS(EXPORTED_FOR_KUNIT_TESTING); 703 + ... 704 + // Use do_interesting_thing() in tests 705 + 706 + For a full example, see this `patch <https://lore.kernel.org/all/20221207014024.340230-3-rmoar@google.com/>`_ 707 + where a test is modified to conditionally expose static functions for testing 708 + using the macros above. 709 + 710 + As an **alternative** to the method above, you could conditionally ``#include`` 711 + the test file at the end of your .c file. This is not recommended but works 712 + if needed. For example: 691 713 692 714 .. code-block:: c 693 715 694 - /* In my_file.c */ 716 + /* In "my_file.c" */ 695 717 696 718 static int do_interesting_thing(); 697 719