Feature option object (feature)

Meson object representing a feature options

Returned by

Feature option object objects are returned by the following functions and methods:

Feature option object methods

feature.allowed()

Returns whether the feature was set to 'enabled' or 'auto'

Signature

(since 0.59.0)

bool allowed()

feature.auto()

Returns whether the feature was set to 'auto'

Signature

bool auto()

feature.disable_auto_if()

Returns the feature, with 'auto' converted to 'disabled' if value is true.

Feature value = true value = false
Auto Disabled Auto
Enabled Enabled Enabled
Disabled Disabled Disabled

Signature

(since 0.59.0)

# Returns the feature, with `'auto'` converted to `'disabled'` if value is true
feature disable_auto_if(
  bool value,     # See the table above
)

Example

disable_auto_if is useful to give precedence to mutually exclusive dependencies (that provide the same API) if either or both are available:

# '-Dfoo=auto -Dbar=enabled' will not pick foo even if installed.
use_bar = get_option('bar')
use_foo = get_option('foo').disable_auto_if(use_bar.enabled())
dep_foo = dependency('foo', required: use_foo)
if not dep_foo.found()
  dep_foo = dependency('bar', required: use_bar)
endif

Arguments

The method feature.disable_auto_if() accepts the following positional arguments:

Name Type Description Tags
value bool

See the table above

feature.disable_if()

Returns the object itself if the value is false; an error if the object is 'enabled' and the value is true; a disabled feature if the object is 'auto' or 'disabled' and the value is true.

Feature value = true value = false
Auto Disabled Auto
Enabled Error Enabled
Disabled Disabled Disabled

This is equivalent to feature_opt.require(not condition), but may make code easier to reason about, especially when mixed with enable_if

Signature

(since 1.1.0)

# Returns the object itself if the value is false; an error if the object is
feature disable_if(
  bool value,     # The value to check

  # Keyword arguments:
  error_message : str  # The error message to print if the check fails
)

Example

disable_if is useful to restrict the applicability of 'auto' features, particularly when passing them to dependency():

use_os_feature = get_option('foo') \
  .disable_if(host_machine.system() == 'darwin', error_message : 'os feature not supported on MacOS')
dep_os_feature = dependency('os_feature', required: use_os_feature)

Arguments

The method feature.disable_if() accepts the following positional arguments:

Name Type Description Tags
value bool

The value to check

Finally, feature.disable_if() accepts the following keyword arguments:

Name Type Description Tags
error_message str

The error message to print if the check fails

default = ''

feature.disabled()

Returns whether the feature was set to 'disabled'

Signature

bool disabled()

feature.enable_auto_if()

Returns the feature, with 'auto' converted to 'enabled' if value is true.

Feature value = true value = false
Auto Enabled Auto
Enabled Enabled Enabled
Disabled Disabled Disabled

Signature

(since 1.1.0)

# Returns the feature, with `'auto'` converted to `'enabled'` if value is true
feature enable_auto_if(
  bool value,     # See the table above
)

Arguments

The method feature.enable_auto_if() accepts the following positional arguments:

Name Type Description Tags
value bool

See the table above

feature.enable_if()

Returns the object itself if the value is false; an error if the object is 'disabled' and the value is true; an enabled feature if the object is 'auto' or 'enabled' and the value is true.

Feature value = true value = false
Auto Enabled Auto
Enabled Enabled Enabled
Disabled Error Disabled

Signature

(since 1.1.0)

# Returns the object itself if the value is false; an error if the object is
feature enable_if(
  bool value,     # The value to check

  # Keyword arguments:
  error_message : str  # The error message to print if the check fails
)

Example

enable_if is useful to restrict the applicability of 'auto' features, particularly when passing them to dependency():

use_llvm = get_option('llvm').enable_if(with_clang).enable_if(with_llvm_libs)
dep_llvm = dependency('llvm', required: use_llvm)

Arguments

The method feature.enable_if() accepts the following positional arguments:

Name Type Description Tags
value bool

The value to check

Finally, feature.enable_if() accepts the following keyword arguments:

Name Type Description Tags
error_message str

The error message to print if the check fails

default = ''

feature.enabled()

Returns whether the feature was set to 'enabled'

Signature

bool enabled()

feature.require()

Returns the object itself if the value is true; an error if the object is 'enabled' and the value is false; a disabled feature if the object is 'auto' or 'disabled' and the value is false.

Feature value = true value = false
Auto Auto Disabled
Enabled Enabled Error
Disabled Disabled Disabled

Signature

(since 0.59.0)

# Returns the object itself if the value is true; an error if the object is
feature require(
  bool value,     # The value to check

  # Keyword arguments:
  error_message : str  # The error message to print if the check fails
)

Example

require is useful to restrict the applicability of 'auto' features, for example based on other features or on properties of the host machine:

if get_option('directx').require(host_machine.system() == 'windows',
      error_message: 'DirectX only available on Windows').allowed() then
  src += ['directx.c']
  config.set10('HAVE_DIRECTX', true)
endif

Arguments

The method feature.require() accepts the following positional arguments:

Name Type Description Tags
value bool

The value to check

Finally, feature.require() accepts the following keyword arguments:

Name Type Description Tags
error_message str

The error message to print if the check fails

default = ''

The results of the search are