diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index a08a40979dece0769a565fe1e7547c5df11709e1..c47a18fd686ce474ad229d1a64a7a3ac916bbd4e 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -762,6 +762,7 @@ INPUT = ../../doc.txt \ ../../pkg \ src/ \ src/mainpage.md \ + src/creating-modules.md \ src/creating-an-application.md \ src/getting-started.md diff --git a/doc/doxygen/src/creating-modules.md b/doc/doxygen/src/creating-modules.md new file mode 100644 index 0000000000000000000000000000000000000000..9786fd1bacbb0100c539c5588c3a4d6d25db0526 --- /dev/null +++ b/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`. diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md index b304f278d8261b89a597e78a2e49a7af4cc766e4..dc28c26548325e951a775cf6c19c0526b24d79c5 100644 --- a/doc/doxygen/src/mainpage.md +++ b/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