Description

There is currently no documentation and usage guide on how to use DEFAULT_MODULE and DISABLE_MODULE. Both tools also have some limitations but these may not be apparent.

This issue wants to open up the discussion on the them and see where we want to allow or limit its use.

Current usage DEFAULT_MODULE and DISABLE_MODULE

makefiles/defaultmodules.inc.mk

This file declares two types of DEFAULT_MODULEs

• periph_init and auto_init: modules that trigger dependency resolution (they include other periph_init_% and auto_init_% modules)

• board cpu core core_init core_msg core_panic sys modules that mostly will never be disabled (and where disabling some of them does nothing, they are still compiled in e.g. sys)

DEFAULT_MODULE declared at application level

The only case so far is tests_utils_interactive_sync included in all test applications

DEFAULT_MODULE by other MODULEs or PKGs

• stdio_rtt
• oneway_malloc
• auto_init_%

DISABLE_MODULE at application level

Used mainly in tests to disable some functions and auto_init_%

DISABLE_MODULE in dependency resolution

There is only one case for this DISABLE_MODULE += stdio_rtt.

Converting DEFAULT_MODULES -> USEMODULE

DEFAULT_MODULES are converted into USEMODULES in two places:

1. Before parsing Makefile.dep:

   RIOT/Makefile.include

   Lines 363 to 364 in efb1136

   	# handle removal of default modules
   	USEMODULE += $(filter-out $(DISABLE_MODULE), $(DEFAULT_MODULE))

2. After the recursive catch only for periph_init_% and auto_init_% modules.

Limitations

Makefile.dep uses a recursive resolution method, it will parse Makefile.dep many times, at the end of each parse it will evaluate USEMODULE and re-parse Makefile.dep. This also means that its designed as an incremental algorithm and is prone to issues when removing MODULEs.

Since we use USEMODULE := $(sort $(USEMODULE)) the order of inclusion becomes relevant and can change build outcome.

To summarize the impact on DEFAULT_MODULE/DISABLE_MODULE

• order of inclusion matters, e.g. DISABLE_MODULE += stdio_rtt in Makefile.dep, this is a case where order of inclusion matters, Makefile.dep: disable stdio_% modules before they are included #13650 fixes the issue in Makefile.dep: DEFAULT_MODULE += stdio_rtt will always load dependencies - even if other stdio is selected #13460 where module dependencies would be included even if the module was disabled.

• Currently only modules added to DEFAULT_MODULE in the first pass will be converted to USEMODULEs

• DEFAULT_MODULE must be disabled in the same iteration they are converted to USEMODULE. (currently this can only happen in the first iteration and for some MODULEs on the last iteration)

• DEFAULT_MODULE/DISABLE_MODULE can not be added to the recursive catch, the recursive catch only works for incrementally adding MODULEs it can not work backwards.

Usage proposal

I've summarized the all possible I could think of here. Some are pretty straight forward, but there are some complicated cases, currently the main one is stdio_rtt and stdio_cdc_acm (c)

(a) Modules that do not trigger dependency resolution and do not depend on another module (e.g.: tests_utils_interactive_sync, oneway_malloc)

These modules can be handled either at the end or at the begging of the iteration through Makefile.dep.

Modules could have a default.inc.mk parsed at the same time as the common default.inc.mk

(b) Modules that trigger dependency resolution and do not depend on another module (e.g.: periph_init, auto_init`)

These modules must be resolved before there dependencies or in the same iteration

(c) Modules that trigger dependency resolution and depend on another module (e.g.: stdi_rtt, stdio_cdc_acm)

These modules must be resolved in the first iteration through Makefile.dep and care must be taken sot that if they are disabled, this must be handled before there dependencies are included #13650.

(d) Modules that do not trigger dependency resolution but depend on another module(e.g.: periph_init_%, auto_init_%)

These modules must be resolved after all its parent modules are resolved, therefore they must be resolved in the last iteration.

Related issues

The issue described in #13460
The fix for the above issue in #13650
Usage of DEFAULT_MODULE #13349 #13648 #13089