make: process include and dep for external modules

Makefile.dep

@@ -5,6 +5,10 @@ OLD_USEPKG := $(sort $(USEPKG))
 # include board dependencies
 -include $(RIOTBOARD)/$(BOARD)/Makefile.dep
 
+# include external modules dependencies
+# processed before RIOT ones to be evaluated before the 'default' rules.
+-include $(EXTERNAL_MODULE_DIRS:%=%/Makefile.dep)
+
 # pull dependencies from sys and drivers
 include $(RIOTBASE)/sys/Makefile.dep
 include $(RIOTBASE)/drivers/Makefile.dep

Makefile.include

@@ -353,6 +353,9 @@ $(RIOTPKG)/%/Makefile.include::
 $(USEPKG:%=$(RIOTPKG)/%/Makefile.include): FORCE
 -include $(USEPKG:%=$(RIOTPKG)/%/Makefile.include)
 
+# include external modules configuration
+-include $(EXTERNAL_MODULE_DIRS:%=%/Makefile.include)
+
 # Deduplicate includes without sorting them
 # see https://stackoverflow.com/questions/16144115/makefile-remove-duplicate-words-without-sorting
 define uniq

doc/doxygen/src/creating-modules.md

@@ -67,8 +67,15 @@ their dependencies.
 Modules outside of RIOTBASE                      {#modules-outside-of-riotbase}
 ===========================
 Modules can be defined outside `RIOTBASE`. In addition to add it to `USEMODULE`
-the user needs to add the path to the module to `EXTERNAL_MODULE_DIRS` and add
-the include path to the API definitions to `INCLUDES`.
+the user needs to add the module path to `EXTERNAL_MODULE_DIRS`.
+
+The external module can optionally define the following files:
+* `Makefile.include` file to set global build configuration like `CFLAGS` or add
+  API headers include paths to the `USEMODULE_INCLUDES` variable.
+* `Makefile.dep` file to set module dependencies
+
+An example can be found in
+[`tests/external_module_dirs`](https://github.com/RIOT-OS/RIOT/tree/master/tests/external_module_dirs)
 
 Pseudomodules                                                  {#pseudomodules}
 =============

tests/external_module_dirs/Makefile

@@ -0,0 +1,10 @@
+APPLICATION = external_module_dirs
+BOARD ?= native
+RIOTBASE ?= $(CURDIR)/../..
+
+USEMODULE += random
+
+USEMODULE += external_module
+EXTERNAL_MODULE_DIRS += $(CURDIR)/external_module
+
+include $(RIOTBASE)/Makefile.include

tests/external_module_dirs/README.md

@@ -0,0 +1,12 @@
+Test of `EXTERNAL_MODULE_DIRS` handling
+=======================================
+
+This is a test for the `EXTERNAL_MODULE_DIRS` variable.
+
+It demonstrates:
+
+ * Adding a module with source code
+ * Setting a header include directory
+ * Adding dependencies, which are evaluated before other modules dependencies
+
+If the application compiles, everything is ok.

tests/external_module_dirs/external_module/Makefile

@@ -0,0 +1 @@
+include $(RIOTBASE)/Makefile.base

tests/external_module_dirs/external_module/Makefile.dep

@@ -0,0 +1,3 @@
+USEMODULE += random
+# Set a different prng than the default prng_tinymt32
+USEMODULE += prng_xorshift

tests/external_module_dirs/external_module/Makefile.include

@@ -0,0 +1,3 @@
+# Use an immediate variable to evaluate `MAKEFILE_LIST` now
+USEMODULE_INCLUDES_external_module := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))/include
+USEMODULE_INCLUDES += $(USEMODULE_INCLUDES_external_module)

tests/external_module_dirs/external_module/external_module.c

@@ -0,0 +1,24 @@
+/*
+ * Copyright (C) 2018 Freie Universität Berlin
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     tests
+ * @{
+ *
+ * @file
+ * @brief       Test the EXTERNAL_MODULE_DIRS feature
+ * @note        Define a shared variable
+ *
+ * @author      Gaëtan Harter <gaetan.harter@fu-berlin.de>
+ *
+ * @}
+ */
+
+#include "external_module.h"
+
+char *external_module_message = "Linking worked";

tests/external_module_dirs/external_module/include/external_module.h

@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2018 Freie Universität Berlin
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @defgroup
+ * @ingroup
+ * @brief
+ * @{
+ *
+ * @file
+ * @brief
+ *
+ * @author  Gaëtan Harter <gaetan.harter@fu-berlin.de>
+ */
+#ifndef EXTERNAL_MODULE_H
+#define EXTERNAL_MODULE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   A simple string message
+ */
+extern char *external_module_message;
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
+#endif /* EXTERNAL_MODULE_H */

tests/external_module_dirs/main.c

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2018 Freie Universität Berlin
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     tests
+ * @{
+ *
+ * @file
+ * @brief       Test the EXTERNAL_MODULE_DIRS feature
+ *
+ * @author      Gaëtan Harter <gaetan.harter@fu-berlin.de>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+#include "external_module.h"
+
+#ifdef MODULE_PRNG_TINYMT32
+#error "Error: it included the default dependency"
+#endif
+
+#ifndef MODULE_PRNG_XORSHIFT
+#error "Dependency not included"
+#endif
+
+int main(void)
+{
+    puts("If it compiles, it works!");
+    printf("Message: %s\n", external_module_message);
+    return 0;
+}