Merge pull request #4480 from authmillenon/doc/enh/creating-modules

doc: add page about creating modules

doc/doxygen/riot.doxyfile

@@ -762,6 +762,7 @@ INPUT                  = ../../doc.txt \
                          ../../sys \
                          src/ \
                          src/mainpage.md \
+                         src/creating-modules.md \
                          src/creating-an-application.md \
                          src/getting-started.md
 

doc/doxygen/src/creating-modules.md

@@ -0,0 +1,65 @@
+Creating modules                                            {#creating-modules}
+================
+Modules in RIOT are well-defined units of code that provide a set of features
+to your application. This includes also drivers and to a certain extent ports
+for CPUs and boards (with some exceptions, see <!-- @ref porting-guide --> the
+porting guide for further information).
+
+The general structure                                  {#the-general-structure}
+=====================
+Like @ref creating-an-application "applications", modules are directories
+containing source files and a Makefile. Additionally their API can be defined
+in one or more header files, residing in the include path of their
+super-module.
+
+E.g. the @ref sys_shell module is implemented in `sys/shell` and defines its
+API in `sys/include/shell.h` and the @ref drivers_isl29020 driver is
+implemented in `drivers/isl29020` and defines its API in
+`drivers/include/isl29020.h`.
+
+A module's Makefile just needs to include `Makefile.base` in the RIOT
+repository:
+
+~~~~~~~~~~~~~~~~~~~ {.mk}
+include $(RIOTBASE)/Makefile
+~~~~~~~~~~~~~~~~~~~
+
+If your module's name differs from the name of the directory it resides in you
+need to set the `MODULE` macro in addition.
+
+When compiled a module always provides a `MODULE_<MODULENAME>` macro to the
+system. This way, other modules can check if the module is available in the
+current configuration or not.
+
+Modules can be used by adding their name to the `USEMODULE` macro of your
+application's Makefile.
+
+Module dependencies
+===================
+Your module may depend on other modules to minimize code duplication. These
+dependencies are defined in `Makefile.dep` with the following syntax:
+
+~~~~~~~~~~~~~~~~~~~ {.mk}
+ifneq (,$(filter your_module,$(USEMODULE))) # if module in USEMODULE
+  USEMODULE += dep1                         # add dependencies to USEMODULE
+  USEMODULE += dep2
+endif
+~~~~~~~~~~~~~~~~~~~
+
+Note, that `Makefile.dep` is processed only once so you have to take care to
+add the dependency block for your module *before* your dependencies pull in
+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_MODULES` and add the
+include path to the API definitions to `INCLUDES`.
+
+Pseudomodules                                                  {#pseudomodules}
+=============
+Pseudomodules are modules that do not have any code. Their main use cases are
+to provide base information for dependencies to other modules or information to
+the code base via the `MODULE_<MODULENAME>` macro. Pseudomodules can provide
+header files too, if need be. To create a pseudomodule just add its name to the
+`PSEUDOMODULES` macro in `Makefile.pseudomodules`.

doc/doxygen/src/mainpage.md

@@ -228,11 +228,13 @@ debugging, reseting (e.g. support for [OpenOCD](http://openocd.org/),
 integration to open testbeds such as the [IoT-LAB](https://www.iot-lab.info/).
 Furthermore you can find here scripts to do all kind of code and style checks.
 
-<!--
 Further information                                      {#further-information}
 ===================
-*TBD*
+ - @ref getting-started
+ - @ref creating-an-application
+ - @ref creating-modules
 
+<!--
 Idea for this section: just name each of RIOT's main features/concepts and link
 to an appropriate page with further information:
     - Create an application