diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 16fcbbf7c..e96a6fc41 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -973,19 +973,21 @@ a non-existing variable will cause a fatal error. ### import() -``` meson - module_object import(module_name) +``` + module_object import(string, required : bool | feature, disabler : bool) ``` -Imports the given extension module. Returns an opaque object that can -be used to call the methods of the module. Here's an example for a -hypothetical `testmod` module. +Imports the given extension module. Returns an object that can be used to call +the methods of the module. Here's an example for a hypothetical `testmod` +module. ```meson tmod = import('testmod') tmod.do_something() ``` +*Since 0.59.0* the required and disabler keyword arguments + ### include_directories() ``` meson @@ -2911,3 +2913,11 @@ sample piece of code with [`compiler.run()`](#compiler-object) or - `returncode()`: the return code of executing the compiled binary - `stderr()`: the standard error produced when the command was run - `stdout()`: the standard out produced when the command was run + +### `module` object + +Modules provide their own specific implementation methods, but all modules +proivide the following methods: + +- `bool found()`: returns True if the module was successfully imported, + otherwise false. *Since 0.59.0* diff --git a/docs/markdown/snippets/required_and_disabled_import.md b/docs/markdown/snippets/required_and_disabled_import.md new file mode 100644 index 000000000..39ca3071d --- /dev/null +++ b/docs/markdown/snippets/required_and_disabled_import.md @@ -0,0 +1,5 @@ +## The `import()` function gains `required` and `disabler` arguments + +In addition, modules now have a `found()` method, like programs and +dependencies. This allows them to be conditionally required, and used in most +places that an object with a `found()` method can be. diff --git a/mesonbuild/interpreter/interpreter.py b/mesonbuild/interpreter/interpreter.py index c103f7ecc..9bc7bd519 100644 --- a/mesonbuild/interpreter/interpreter.py +++ b/mesonbuild/interpreter/interpreter.py @@ -32,7 +32,7 @@ from ..interpreterbase import Disabler, disablerIfNotFound from ..interpreterbase import FeatureNew, FeatureDeprecated, FeatureNewKwargs, FeatureDeprecatedKwargs from ..interpreterbase import ObjectHolder, RangeHolder from ..interpreterbase import TYPE_nkwargs, TYPE_nvar, TYPE_var -from ..modules import ExtensionModule, ModuleObject, MutableModuleObject, NewExtensionModule +from ..modules import ExtensionModule, ModuleObject, MutableModuleObject, NewExtensionModule, NotFoundExtensionModule from ..cmake import CMakeInterpreter from ..backend.backends import Backend, ExecutableSerialisation @@ -161,6 +161,13 @@ _INSTALL_MODE_KW = KwargInfo( convertor=_install_mode_convertor, ) +_REQUIRED_KW = KwargInfo( + 'required', + (bool, coredata.UserFeatureOption), + default=True, + # TODO: extract_required_kwarg could be converted to a convertor +) + def stringifyUserArguments(args, quote=False): if isinstance(args, list): @@ -304,7 +311,7 @@ class Interpreter(InterpreterBase, HoldableObject): subproject: str = '', subdir: str = '', subproject_dir: str = 'subprojects', - modules: T.Optional[T.Dict[str, T.Union[ExtensionModule, NewExtensionModule]]] = None, + modules: T.Optional[T.Dict[str, T.Union[ExtensionModule, NewExtensionModule, NotFoundExtensionModule]]] = None, default_project_options: T.Optional[T.Dict[str, str]] = None, mock: bool = False, ast: T.Optional[mparser.CodeBlockNode] = None, @@ -601,33 +608,47 @@ class Interpreter(InterpreterBase, HoldableObject): dep = df.lookup(kwargs, force_fallback=True) self.build.stdlibs[for_machine][l] = dep + def _import_module(self, modname: str, required: bool) -> T.Union[ExtensionModule, NewExtensionModule, NotFoundExtensionModule]: + if modname in self.modules: + return self.modules[modname] + try: + module = importlib.import_module('mesonbuild.modules.' + modname) + except ImportError: + if required: + raise InvalidArguments(f'Module "{modname}" does not exist') + ext_module = NotFoundExtensionModule() + else: + ext_module = module.initialize(self) + assert isinstance(ext_module, (ExtensionModule, NewExtensionModule)) + self.modules[modname] = ext_module + return ext_module + @typed_pos_args('import', str) - @noKwargs - def func_import(self, node: mparser.BaseNode, args: T.Tuple[str], kwargs) -> ModuleObject: + @typed_kwargs( + 'import', + _REQUIRED_KW.evolve(since='0.59.0'), + KwargInfo('disabler', bool, default=False, since='0.59.0'), + ) + @disablerIfNotFound + def func_import(self, node: mparser.BaseNode, args: T.Tuple[str], + kwargs: 'kwargs.FuncImportModule') -> T.Union[ExtensionModule, NewExtensionModule, NotFoundExtensionModule]: modname = args[0] + disabled, required, _ = extract_required_kwarg(kwargs, self.subproject) + if disabled: + return NotFoundExtensionModule() + if modname.startswith('unstable-'): plainname = modname.split('-', 1)[1] try: # check if stable module exists - self._import_module(plainname) + mod = self._import_module(plainname, required) + # XXX: this is acutally not helpful, since it doesn't do a version check mlog.warning(f'Module {modname} is now stable, please use the {plainname} module instead.') - modname = plainname + return mod except InvalidArguments: mlog.warning('Module %s has no backwards or forwards compatibility and might not exist in future releases.' % modname, location=node) modname = 'unstable_' + plainname - - if modname in self.modules: - return self.modules[modname] - - try: - module = importlib.import_module('mesonbuild.modules.' + modname) - except ImportError: - raise InvalidArguments(f'Module "{modname}" does not exist') - ext_module = module.initialize(self) - assert isinstance(ext_module, ModuleObject) - self.modules[modname] = ext_module - - return ext_module + return self._import_module(modname, required) @stringArgs @noKwargs diff --git a/mesonbuild/interpreter/kwargs.py b/mesonbuild/interpreter/kwargs.py index 3c3ecf641..b92b66fd7 100644 --- a/mesonbuild/interpreter/kwargs.py +++ b/mesonbuild/interpreter/kwargs.py @@ -132,3 +132,8 @@ class FuncInstallMan(TypedDict): install_dir: T.Optional[str] install_mode: FileMode locale: T.Optional[str] + + +class FuncImportModule(ExtractRequired): + + disabler: bool diff --git a/mesonbuild/modules/__init__.py b/mesonbuild/modules/__init__.py index ab8534e36..19de1bd1e 100644 --- a/mesonbuild/modules/__init__.py +++ b/mesonbuild/modules/__init__.py @@ -106,6 +106,7 @@ class ModuleObject(HoldableObject): class MutableModuleObject(ModuleObject): pass + # FIXME: Port all modules to stop using self.interpreter and use API on # ModuleState instead. Modules should stop using this class and instead use # ModuleObject base class. @@ -119,7 +120,11 @@ class ExtensionModule(ModuleObject): @noPosargs @noKwargs - def found_method(self, args: T.List['TYPE_var'], kwargs: 'TYPE_kwargs') -> bool: + def found_method(self, state: 'ModuleState', args: T.List['TYPE_var'], kwargs: 'TYPE_kwargs') -> bool: + return self.found() + + @staticmethod + def found() -> bool: return True @@ -130,7 +135,7 @@ class NewExtensionModule(ModuleObject): provides the found method. """ - def __init__(self): + def __init__(self) -> None: super().__init__() self.methods.update({ 'found': self.found_method, @@ -138,26 +143,23 @@ class NewExtensionModule(ModuleObject): @noPosargs @noKwargs - def found_method(self, args: T.List['TYPE_var'], kwargs: 'TYPE_kwargs') -> bool: + def found_method(self, state: 'ModuleState', args: T.List['TYPE_var'], kwargs: 'TYPE_kwargs') -> bool: + return self.found() + + @staticmethod + def found() -> bool: return True -class NotFoundExtensionModule(ModuleObject): +class NotFoundExtensionModule(NewExtensionModule): """Class for modern modules provides the found method. """ - def __init__(self): - super().__init__() - self.methods.update({ - 'found': self.found_method, - }) - - @noPosargs - @noKwargs - def found_method(self, args: T.List['TYPE_var'], kwargs: 'TYPE_kwargs') -> bool: + @staticmethod + def found() -> bool: return False diff --git a/test cases/common/67 modules/meson.build b/test cases/common/67 modules/meson.build index e9750cd97..ad33ed6d4 100644 --- a/test cases/common/67 modules/meson.build +++ b/test cases/common/67 modules/meson.build @@ -2,3 +2,13 @@ project('module test', 'c') modtest = import('modtest') modtest.print_hello() +assert(modtest.found()) + +modtest = import('modtest', required : get_option('disabled')) +assert(not modtest.found()) + +notfound = import('not-found', required : false) +assert(not notfound.found()) + +disabled = import('not-found', required : false, disabler : true) +assert(is_disabler(disabled)) diff --git a/test cases/common/67 modules/meson_options.txt b/test cases/common/67 modules/meson_options.txt new file mode 100644 index 000000000..06711447d --- /dev/null +++ b/test cases/common/67 modules/meson_options.txt @@ -0,0 +1,6 @@ +option( + 'disabled', + type : 'feature', + value : 'disabled', + description : 'test disabled' +) diff --git a/test cases/failing/57 kwarg in module/meson.build b/test cases/failing/57 kwarg in module/meson.build deleted file mode 100644 index b105db152..000000000 --- a/test cases/failing/57 kwarg in module/meson.build +++ /dev/null @@ -1,5 +0,0 @@ -project('module test', 'c') - -modtest = import('modtest', i_cause: 'a_build_failure') -modtest.print_hello() - diff --git a/test cases/failing/57 kwarg in module/test.json b/test cases/failing/57 kwarg in module/test.json deleted file mode 100644 index cafb3ab64..000000000 --- a/test cases/failing/57 kwarg in module/test.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "stdout": [ - { - "line": "test cases/failing/57 kwarg in module/meson.build:3:0: ERROR: Function does not take keyword arguments." - } - ] -}