lib: add custom_lib

Enhance the example-application repository with a configurable,
trivial library example and associated test cases.
.
This implementation appears to make no assumptions.
.
This implementation was verified by running the following commands
in an example-application workspace and verifying all tests passed.
  1. `west build -b native_posix -p always example-application/tests/lib/custom_lib/`
  2. `./build/zephyr/zephyr.exe`
  3. `west build -b native_posix -p always example-application/tests/lib/custom_lib/ -- -DCONFIG_CUSTOM_LIB_GET_VALUE_DEFAULT=6`
  4. `./build/zephyr/zephyr.exe`
  5. `zephyr/scripts/twister -T example-application/tests/ \
      -p qemu_cortex_m0`
  6. `cd zephyr/doc && make clean && make` built cleanly.
.
Note that `twister` does not follow the `zephyr/module.yml:tests`
setting to discover tests in modules, so the testcase-root must be
explicitly provided.

Fixes #35177

Signed-off-by: Gregory Shue <gregory.shue@legrand.us>

.github/workflows/build.yml

@@ -27,6 +27,11 @@ jobs:
         run: |
           west build -b custom_plank app
 
+      - name: Twister Unit Tests
+        working-directory: example-application
+        run: |
+          ../zephyr/scripts/twister -p qemu_cortex_m0 --testcase-root ./tests/
+
       - name: Archive firmware
         uses: actions/upload-artifact@v2
         with:

CMakeLists.txt

@@ -4,5 +4,7 @@
 # This CMake file is picked by the Zephyr build system because it is defined
 # as the module CMake entry point (see zephyr/module.yml).
 
+zephyr_include_directories(include)
+
 add_subdirectory(drivers)
 add_subdirectory(lib)

include/custom_lib/custom_lib.h

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2021, Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef EXAMPLE_APPLICATION_INCLUDE_CUSTOM_LIB_CUSTOM_LIB_H_
+#define EXAMPLE_APPLICATION_INCLUDE_CUSTOM_LIB_CUSTOM_LIB_H_
+
+/**
+ * @brief Return parameter if non-zero, or Kconfig-controlled default
+ *
+ * Function returns the provided value if non-zero, or a Kconfig-controlled
+ * default value if the parameter is zero.  This trivial function is
+ * provided in order to have a library interface example that is trivial 
+ * to test.
+ *
+ * @param return_value_if_nonzero Value to return if non-zero
+ * @returns return_value_if_nonzero when the parameter is non-zero
+ * @returns CONFIG_CUSTOM_LIB_GET_VALUE_DEFAULT if parameter is zero
+ */
+int custom_lib_get_value(int return_value_if_nonzero);
+
+#endif /* EXAMPLE_APPLICATION_INCLUDE_CUSTOM_LIB_CUSTOM_LIB_H_ */

lib/CMakeLists.txt

@@ -1,6 +1,3 @@
 # SPDX-License-Identifier: Apache-2.0
 
-# The visibility and compilation of libraries may be controlled
+add_subdirectory_ifdef(CONFIG_CUSTOM_LIB custom_lib)
-# with a Kconfig setting as follows:
-#
-#   add_subdirectory_ifdef(CONFIG_CUSTOM_LIB              custom_lib)

lib/Kconfig

@@ -3,4 +3,6 @@
 
 menu "Libraries"
 
+rsource "custom_lib/Kconfig"
+
 endmenu

lib/custom_lib/CMakeLists.txt

@@ -0,0 +1,5 @@
+# Copyright (c) 2021, Legrand North America, LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+zephyr_library()
+zephyr_library_sources(custom_lib.c)

lib/custom_lib/Kconfig

@@ -0,0 +1,19 @@
+# Copyright (c) 2021, Legrand North America, LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+config CUSTOM_LIB
+	bool "custom_lib Support"
+	help 
+	  This option enables the custom_lib library
+
+config CUSTOM_LIB_GET_VALUE_DEFAULT
+	int "custom_lib_get_value() default return value"
+	depends on CUSTOM_LIB
+	default 0 
+	help
+	  This option primarily exists as an example of a library Kconfig
+	  setting.
+
+	  This option specifies the value for custom_lib_get_value()
+	  to return when the input parameter is zero.  (Otherwise
+	  the function returns the input parameter value.)

lib/custom_lib/custom_lib.c

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) 2021, Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <custom_lib/custom_lib.h>
+
+int custom_lib_get_value(int return_value_if_nonzero)
+{
+	return (return_value_if_nonzero != 0) ? return_value_if_nonzero
+		: CONFIG_CUSTOM_LIB_GET_VALUE_DEFAULT;
+}

tests/lib/custom_lib/CMakeLists.txt

@@ -0,0 +1,9 @@
+# Copyright (c) 2021, Legrand North America, LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.13.1)
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(custom_lib)
+
+FILE(GLOB app_sources src/*.c)
+target_sources(app PRIVATE ${app_sources})

tests/lib/custom_lib/prj.conf

@@ -0,0 +1,2 @@
+CONFIG_ZTEST=y
+CONFIG_CUSTOM_LIB=y

tests/lib/custom_lib/src/main.c

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2021 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * @file test custom_lib library
+ *
+ * This suite verifies that the methods provided with the custom_lib
+ * library works correctly.
+ */
+
+#include <zephyr.h>
+#include <ztest.h>
+#include <custom_lib/custom_lib.h>
+
+static void test_get_value(void)
+{
+	/* Verify standard behavior */
+	zassert_equal(custom_lib_get_value(INT_MIN), INT_MIN,
+		"get_value failed input of INT_MIN");
+	zassert_equal(custom_lib_get_value(INT_MIN + 1), INT_MIN + 1,
+		"get_value failed input of INT_MIN + 1");
+	zassert_equal(custom_lib_get_value(-1), -1,
+		"get_value failed input of -1");
+	zassert_equal(custom_lib_get_value(1), 1,
+		"get_value failed input of 1");
+	zassert_equal(custom_lib_get_value(INT_MAX - 1), INT_MAX - 1,
+		"get_value failed input of INT_MAX - 1");
+	zassert_equal(custom_lib_get_value(INT_MAX), INT_MAX,
+		"get_value failed input of INT_MAX");
+
+	/* Verify override behavior */
+	zassert_equal(custom_lib_get_value(0),
+		CONFIG_CUSTOM_LIB_GET_VALUE_DEFAULT,
+		"get_value failed input of 0");
+}
+
+void test_main(void)
+{
+	ztest_test_suite(lib_custom_lib_test,
+			 ztest_unit_test(test_get_value)
+			 );
+
+	ztest_run_test_suite(lib_custom_lib_test);
+}

tests/lib/custom_lib/testcase.yaml

@@ -0,0 +1,7 @@
+common:
+  tags: extensibility
+tests:
+  lib.custom_lib:
+    build_only: false   # something benign to make a non-empty list
+  lib.custom_lib.non_default:
+    extra_args: CONFIG_CUSTOM_LIB_GET_VALUE_DEFAULT=6