Meson: Deprecating project options

[dcbaker]

In mesa we are trying to migrate a number of options from combo types to feature types. Our combos predate features, and use true, false, and auto instead of enabled, disabled, and auto, so I;ve added enabled and disabled, and added code around each option to emit a warning about using true or false and convert it to enabled or disabled. Meson should be able to handle this automatically. I'm proposing adding a new keyword to the option() function, deprecated, that would take either a boolean, a string, an array, or a dict, and would work like this,

option(
  ...
 deprecated : true,
)

This option is completely deprecated, meson would emit a " is deprecated"

option(
  ...
  deprecated : "This option will be removed in 1.0"
)

In this case the message would be printed verbatim

option(
  type : 'array',  # or combo
  choices : ['foo', 'bar', 'other', 'thing'],
  deprecated : ['foo', 'bar'],
)

foo and bar are deprecated, and meson will emit a message as such.

option(
  type : 'array',  # or combo or possibly feature?
  choices : ['foo', 'bar', 'other', 'thing'],
  deprecated : {
    'foo': 'other',
    'bar': 'thing',
  }
)

meson would emit a warning that the key used is deprecated and replaced with the value of the dict instead, and meson would remap the value to be the non-deprecated value.

Additionally, for cases that an option has been replaced by a different option, the deprecated_for keyword can be used

option(
  'oldopt',
  deprecated : true,
  deprecated_for : 'newoption',
)
option(
  'newoption',
  ..
)

Does this all seem resonable, does it seem like too much? things I've missed?

[dcbaker]

@xclaesse, as discussed on irc. (I don't know __tim's github nick, so if you can mention them).

[xclaesse]

I like this a lot. I would like to add an extra case:

option('foo',
  type: 'feature',
  deprecated: {
    'true': 'enabled',
    'false': 'auto',
  },
)

With that syntax, the feature option would have the extra "true" and 'false' choices that would be mapped accordingly. This would allow Mesa to make the switch to a feature option immadiately while still having -Dfoo=true and -Dfoo=false working. Note that providing the mapping is important, meson cannot do it itself because false is ambigous and could mean disabled or auto.

[dcbaker]

Yeah, I think that makes sense as well, since for mesa in most cases false would map to disabled not auto

[xclaesse]

Btw __tim is @tp-m

[tp-m]

Looks great to me!

[xclaesse]

One deprecation case I bump into is renaming an option.

-Doldname=value should keep working and set value on newname.

option(
  ...
 deprecated : true,
 alias: 'newname',
)

Or deprecated: 'newname' ?

[tp-m]

Or deprecated: 'newname' ?

Was going to suggest deprecated_for: 'newname'

[xclaesse]

Was wondering if alias could be useful even outside of deprecation mechanism, it could help with consistency issues we have in GNOME where some modules have doc, docs, gtk_doc and all similar variants. Thinking out loud here, but parent project could define aliases for all those variants so setting that option on parent will work for all subprojects that have similar yielding option.

@tp-m see gst-build have both doc and gtk_doc. Ideally -Ddoc=disabled should disable gtk_doc in glib subproject.

[xclaesse]

Or deprecated: 'newname' ?

Was going to suggest deprecated_for: 'newname'

Good point, I prefer deprecated_for instead of playing with the type of deprecated being bool or string.

[dcbaker]

I like the deprecated_for as well. deprecated is pretty well overloaded in this proposal as is

[dcbaker]

I've updated the main proposal. But, logically, what do we do in cases where the values of the old option need to be remapped for the new option? we could use the mapping in deprecated for that too. does that make sense?

[xclaesse]

Something like that I think:

option('newoption', type: 'combo', choices : ['foo', 'bar', 'other', 'thing'])
option('oldoption', type: 'boolean', deprecated_for: 'newoption', deprecated: {'true': 'foo', 'false': 'bar'})

-Doldoption=true is same as doing -Dnewoption=foo. Does that make sense?

Or deprecation mapping should be on newoption to allow -Dnewoption=true?

[xclaesse]

Probably should forbid having both -Dnewoption and -Doldoption on the command line, because relying on ordering is annoying. We already have that case with buildtype VS optimisation+debug and it's a pain.

[bonzini]

A deprecation_message would be useful as well if the deprecated argument is squatted by the remapping.