documentation: the build system

[cladmi]

Description

This is an issue to follow steps for documenting the build system.
This a subtask of #4309.

I welcome all points that you would like to add in the subtasks and will update the current one with PRs.

Goal

Add technical documentation regarding the build system in general, advanced topics and internals.
It should describe how things are achieved and also document the limitations.

My second goal is to use this documentation as reference when designing build system upgrades.

Subtasks ideas

• Steps by steps, line by line, from application Makefile to Makefile.base
• Describe FEATURES
• Provide options for a module (see ref make: Setting constants on compile time doesn't really set them everywhere #3256)
• Describe dependencies management based on the goal and how to achieve it
  • Simple dependency
  • Dependencies on features
  • Default implementation
  • Optional dependencies
• C handling of dependencies
  • Periph Common https://github.com/RIOT-OS/RIOT/blob/2017.10/drivers/periph_common/flashpage.c#L26
  • PM https://github.com/RIOT-OS/RIOT/blob/2017.10/drivers/periph_common/pm.c#L27
  • Auto init https://github.com/RIOT-OS/RIOT/blob/2017.10/sys/auto_init/saul/auto_init_adc.c
  • Shell https://github.com/RIOT-OS/RIOT/blob/2017.10/sys/shell/commands/shell_commands.c
• Modules with a Makefile.include
• Describe when make clean is required
• Boards/CPUS
• Replace mentions to EXTERNAL_MODULES in http://api.riot-os.org/creating-modules.html
• Same topics but for packages (deps, private flags, public flags)
• When are 'export VARIABLE' needed in makefiles and remove useless ones

[roberthartung]

Regarding PM: I started to edit the wiki, but didn't finish it yet https://github.com/RIOT-OS/RIOT/wiki/Power-Management .

[bergzand]

@cladmi Any progress here?

[cladmi]

I have more been fighting with some inconsistencies than writing anything unfortunately :/
I should spend some time on it in parallel.