kscreenctl: New utility

kscreenctl provides a more conventional command line interface in comparison to kscreen-doctor, i.e.

kscreenctl commmand

or

kscreenctl OUTPUT command

For example,

kscreenctl identify

or

kscreenctl active-output calibrate-hdr

One of the goals was to make sure that the help message automatically adjusts to new commands. kscreen-doctor gained a bunch of new commands but they are poorly documented. kscreenctl solves it by storing all commands and options in special sections that are inspected at runtime to build help messages.

Unfortunately, shell completion still requires manual adjusting. There are some ideas how to generate shell completion automatically, but it's on backburner because it's all quite convoluted.

Shell completion is provided only for zsh and fish.

In order to add a new command, you will need to add a cpp file whose name matches the command name. Then add an OUTPUT_COMMAND or a COMMAND macro to register the function that will be called when the user types that command. You may also need to update shell completion files.

The purpose of kscreenctl is to replace kscreen-doctor.

On the technical level, the most important bits are __attribute__((used, retain, section("COMMAND"), aligned(sizeof(void *)))) and

extern const Command __start_COMMAND[];
extern const Command __stop_COMMAND[];
return std::span(__start_COMMAND, __stop_COMMAND);

The __attribute__(section("COMMAND")) is used to register supported commands. The Command structures are stored in the COMMAND section, which can be accessed using __start_COMMAND and __stop_COMMAND. We then walk through all available commands to find the matching command for the specified CLI arguments.

The main advantage of the __attribute__(section("COMMAND")) approach is that it allows to add new commands with very little boilerplate code.