Adding more information into the "make" cli

Development
1

I probably am not the only one that likes to save a few minutes of reading documentation by spending hours of trial and error or quickly implementing an already implemented feature…

Since we use make as our own CLI, I wonder if we should put a little more effort into including documentation in make.

We do have make help that simply lists some targets. Within these targets we have info-* but I somehow think we can do better. The immediate thing would be to have at least a description of each of targets and maybe also a way to show a subset of env variables, the usage and description.

Something like:

> make help
all - builds the application
...
info-boards - prints all boards
info-boards-supported - prints all boards supported for this application
...
info-env-vars - describes common env variables used in RIOT for option setting
...
test - runs automated test for the application if it exists
...

> make info-env-vars
BUILD_IN_DOCKER
Description: Builds the the riotbuild docker container instead of host system
Usage: BUILD_IN_DOCKER=1

BOARD
Description: Selects the board to execute commands on, check info-boards-supported for information on which boards can be used
Usage: BOARD=native, BOARD=nucleo-f103rb

PORT
...

PROG_DEV
...

PROGRAMMER
...

for example.

I guess I would like to know if it makes sense or if it is just me that likes having documentation at hand. Maybe also some if there are some clever ways of adding an maintaining it rather than just printing the information. I somehow want one information source so we don’t have docs and the make info out of sync. Eventually we can think about how to enforce people provide documentation when adding targets…

Suggestions?

2 Likes
2

In general this sounds like a good idea. However, I am fearing that there might be some rot happening since there is no logical connection between targets and documentation. Not sure if there is a tool for that or if you can fetch the commands somehow to check if something is undocumented / a documented command does not exist.

3

Here is how Linux is doing it linux/Makefile at 9f1abbe97c08ba7ed609791627533a805a1b2c66 · torvalds/linux · GitHub

They even split the command description between multiple makefiles using recursive Make.

We could try to come up with some convention on the command names to verify that they have their documented version (e.g. info-boards-doc for info-boards). We could even go one step further and try to namespace targets that are part of the user-facing CLI?

4

According to https://marmelab.com/blog/2016/02/29/auto-documented-makefile.html we may be able to have some ## thing to provide it, at least they would live together then.

2 Likes