Merge pull request #21476 from mguetschow/examples-subfolders-external-module

examples/basic/subfolders: switch from DIRS to EXTERNAL_MODULE_DIRS

Author: mguetschow

examples/basic/subfolders/Makefile

@@ -8,8 +8,8 @@ BOARD ?= native
 RIOTBASE ?= $(CURDIR)/../../..
 
 # Add subfolders as modules
-DIRS += module
-USEMODULE += my_module # name as defined in module/Makefile
+EXTERNAL_MODULE_DIRS += $(CURDIR)/external_modules/
+USEMODULE += module # module name must match folder name
 
 # Add source files in subfolders manually
 SRC += main.c
@@ -18,9 +18,9 @@ SRC += folder/a.c folder/subfolder/b.c folder/subfolder/c.c
 # Alternative method to add files in subfolders using wildcards
 # SRC += $(wildcard *.c folder/*.c folder/**/*.c)
 
-# Adding subfolders both via SRC and DIRS will generate a warning
-# and likely fail during linking
-# DIRS += folder
+# Adding files in subfolders both via SRC and EXTERNAL_MODULE_DIRS
+# will generate a warning and likely fail during linking
+# SRC += external_modules/module/a.c
 
 # Comment this out to disable code in RIOT that does safety checking
 # which is not needed in a production environment but helps in the

examples/basic/subfolders/README.md

@@ -1,8 +1,8 @@
 # Application Example with Subfolders
 
 This example demonstrates the usage of subfolders in a RIOT application
-(or in a RIOT module in general) show-casing two possible approaches: RIOT
-modules and simple subfolders.
+(or in a RIOT module in general) show-casing two possible approaches:
+External RIOT modules and simple subfolders.
 
 ## Details
 
@@ -12,16 +12,18 @@ while the source files in `folder` are considered part of the application itself
 
 ```
 .
+├── external_modules
+│   └── module
+│       ├── a.c
+│       ├── b.c
+│       └── Makefile
 ├── folder
 │   ├── a.c
 │   └── subfolder
-│       └── b.c
+│       ├── b.c
+│       └── c.c
 ├── main.c
 ├── Makefile
-├── module
-│   ├── a.c
-│   ├── b.c
-│   └── Makefile
 └── README.md
 ```
 
@@ -30,14 +32,11 @@ while the source files in `folder` are considered part of the application itself
 At a minimum, each module in RIOT requires a `Makefile` with the following content:
 
 ```Makefile
-MODULE := my_module
-
 include $(RIOTBASE)/Makefile.base
 ```
 
-If `MODULE` is not specified, the name of the module's directory is automatically used,
-leaving only the last line as minimal content.
-It is important to note that module names have to be unique both among _all_ RIOT modules,
+The name of the module's directory is automatically used as the module name.
+It is important to note that module names have to be unique among _all_ RIOT modules,
 i.e., including the modules that are part of RIOT itself.
 
 If not manually specified via `SRC`, all source files which reside
@@ -47,12 +46,13 @@ RIOT modules are also described in greater detail [in the documentation](https:/
 Two lines need to be added to the application's Makefile in order to compile and use the module:
 
 ```Makefile
-DIRS += module
-USEMODULE += my_module
+EXTERNAL_MODULE_DIRS += $(CURDIR)/external_modules/
+USEMODULE += module
 ```
 
-The string added to `DIRS` has to match the directory name,
-while the string added to `USEMODULE` has to match the module's name as defined above.
+The path added to `EXTERNAL_MODULE_DIRS` is the parent directory of the external module,
+while the string added to `USEMODULE` has to match the module's directory name.
+External modules are described in greater detail [in the documentation](https://doc.riot-os.org/creating-an-application.html#autotoc_md2308).
 
 
 ### Subfolders

examples/basic/subfolders/module/Makefile renamed to examples/basic/subfolders/external_modules/module/Makefile

@@ -1,3 +1 @@
-MODULE := my_module
-
 include $(RIOTBASE)/Makefile.base

examples/basic/subfolders/module/a.c renamed to examples/basic/subfolders/external_modules/module/a.c

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+
+import sys
+from testrunner import run
+
+
+def testfunc(child):
+    child.expect_exact('./main.c')
+    child.expect_exact('./module/a.c')
+    child.expect_exact('./module/b.c')
+    child.expect_exact('./folder/a.c')
+    child.expect_exact('./folder/subfolder/b.c')
+    child.expect_exact('./folder/subfolder/c.c')
+
+
+if __name__ == "__main__":
+    sys.exit(run(testfunc))