Allow marking Varlink interfaces, methods, errors, types, fields and
enum values as experimental, for documentation and discoverability.
Calls are not refused.
- One SD_VARLINK_EXPERIMENTAL flag works for interface, symbol and
field flags; _FULL variants of the definition macros take flags.
Interface and symbol flags are now validated, and the internal
_SD_VARLINK_*_FLAGS_MAX are replaced by _SD_VARLINK_*_FLAGS_ALL.
- The IDL output shows experimental items with a "# [Experimental]"
comment line, and sd_varlink_idl_parse() turns it back into the flag,
so the information survives GetInterfaceDescription.
- varlink_idl_consistent() refuses non-experimental fields referring to
experimental types, non-nullable experimental fields in
non-experimental symbols, and experimental values in
non-experimental enums. These rules are deliberately strict, so that
they can be relaxed later without breaking anything.
- varlinkctl highlights experimental methods in list-methods and shows
a notice when calling one (only when on a terminal).
- docs/PORTABILITY_AND_STABILITY.md now excludes experimental parts of
Varlink interfaces from the stability promise.
- Fixes resolution of named types within anonymous types in the parser,
which the new checks ran into.
- io.systemd.PCRLock is marked experimental as a first user; other
experimental components will follow once the design is settled.
Open questions:
- Should experimental values in non-experimental enums be permitted in
some cases, e.g. for enums only used as input?
- Should experimental errors be allowed in non-experimental interfaces?
The IDL does not link errors to methods, so this is documentation
only.
Paul Meyer
a923ab5ed1
