frida 16.2.1 → 16.2.2

package/releng/meson/mesonbuild/modules/hotdoc.py

@@ -0,0 +1,487 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2018 The Meson development team
+
+from __future__ import annotations
+
+'''This module provides helper functions for generating documentation using hotdoc'''
+
+import os, subprocess
+import typing as T
+
+from . import ExtensionModule, ModuleReturnValue, ModuleInfo
+from .. import build, mesonlib, mlog
+from ..build import CustomTarget, CustomTargetIndex
+from ..dependencies import Dependency, InternalDependency
+from ..interpreterbase import (
+    InvalidArguments, noPosargs, noKwargs, typed_kwargs, FeatureDeprecated,
+    ContainerTypeInfo, KwargInfo, typed_pos_args
+)
+from ..interpreter.interpreterobjects import _CustomTargetHolder
+from ..interpreter.type_checking import NoneType
+from ..mesonlib import File, MesonException
+from ..programs import ExternalProgram
+
+if T.TYPE_CHECKING:
+    from typing_extensions import TypedDict
+
+    from . import ModuleState
+    from ..environment import Environment
+    from ..interpreter import Interpreter
+    from ..interpreterbase import TYPE_kwargs, TYPE_var
+
+    _T = T.TypeVar('_T')
+
+    class GenerateDocKwargs(TypedDict):
+        sitemap: T.Union[str, File, CustomTarget, CustomTargetIndex]
+        index: T.Union[str, File, CustomTarget, CustomTargetIndex]
+        project_version: str
+        html_extra_theme: T.Optional[str]
+        include_paths: T.List[str]
+        dependencies: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]]
+        depends: T.List[T.Union[CustomTarget, CustomTargetIndex]]
+        gi_c_source_roots: T.List[str]
+        extra_assets: T.List[str]
+        extra_extension_paths: T.List[str]
+        subprojects: T.List['HotdocTarget']
+        install: bool
+
+def ensure_list(value: T.Union[_T, T.List[_T]]) -> T.List[_T]:
+    if not isinstance(value, list):
+        return [value]
+    return value
+
+
+MIN_HOTDOC_VERSION = '0.8.100'
+
+file_types = (str, File, CustomTarget, CustomTargetIndex)
+
+
+class HotdocExternalProgram(ExternalProgram):
+    def run_hotdoc(self, cmd: T.List[str]) -> int:
+        return subprocess.run(self.get_command() + cmd, stdout=subprocess.DEVNULL).returncode
+
+
+class HotdocTargetBuilder:
+
+    def __init__(self, name: str, state: ModuleState, hotdoc: HotdocExternalProgram, interpreter: Interpreter, kwargs):
+        self.hotdoc = hotdoc
+        self.build_by_default = kwargs.pop('build_by_default', False)
+        self.kwargs = kwargs
+        self.name = name
+        self.state = state
+        self.interpreter = interpreter
+        self.include_paths: mesonlib.OrderedSet[str] = mesonlib.OrderedSet()
+
+        self.builddir = state.environment.get_build_dir()
+        self.sourcedir = state.environment.get_source_dir()
+        self.subdir = state.subdir
+        self.build_command = state.environment.get_build_command()
+
+        self.cmd: T.List[TYPE_var] = ['conf', '--project-name', name, "--disable-incremental-build",
+                                      '--output', os.path.join(self.builddir, self.subdir, self.name + '-doc')]
+
+        self._extra_extension_paths = set()
+        self.extra_assets = set()
+        self.extra_depends = []
+        self._subprojects = []
+
+    def process_known_arg(self, option: str, argname: T.Optional[str] = None, value_processor: T.Optional[T.Callable] = None) -> None:
+        if not argname:
+            argname = option.strip("-").replace("-", "_")
+
+        value = self.kwargs.pop(argname)
+        if value is not None and value_processor:
+            value = value_processor(value)
+
+        self.set_arg_value(option, value)
+
+    def set_arg_value(self, option: str, value: TYPE_var) -> None:
+        if value is None:
+            return
+
+        if isinstance(value, bool):
+            if value:
+                self.cmd.append(option)
+        elif isinstance(value, list):
+            # Do not do anything on empty lists
+            if value:
+                # https://bugs.python.org/issue9334 (from 2010 :( )
+                # The syntax with nargs=+ is inherently ambiguous
+                # A workaround for this case is to simply prefix with a space
+                # every value starting with a dash
+                escaped_value = []
+                for e in value:
+                    if isinstance(e, str) and e.startswith('-'):
+                        escaped_value += [' %s' % e]
+                    else:
+                        escaped_value += [e]
+                if option:
+                    self.cmd.extend([option] + escaped_value)
+                else:
+                    self.cmd.extend(escaped_value)
+        else:
+            # argparse gets confused if value(s) start with a dash.
+            # When an option expects a single value, the unambiguous way
+            # to specify it is with =
+            if isinstance(value, str):
+                self.cmd.extend([f'{option}={value}'])
+            else:
+                self.cmd.extend([option, value])
+
+    def check_extra_arg_type(self, arg: str, value: TYPE_var) -> None:
+        if isinstance(value, list):
+            for v in value:
+                self.check_extra_arg_type(arg, v)
+            return
+
+        valid_types = (str, bool, File, build.IncludeDirs, CustomTarget, CustomTargetIndex, build.BuildTarget)
+        if not isinstance(value, valid_types):
+            raise InvalidArguments('Argument "{}={}" should be of type: {}.'.format(
+                arg, value, [t.__name__ for t in valid_types]))
+
+    def process_extra_args(self) -> None:
+        for arg, value in self.kwargs.items():
+            option = "--" + arg.replace("_", "-")
+            self.check_extra_arg_type(arg, value)
+            self.set_arg_value(option, value)
+
+    def get_value(self, types, argname, default=None, value_processor=None,
+                  mandatory=False, force_list=False):
+        if not isinstance(types, list):
+            types = [types]
+        try:
+            uvalue = value = self.kwargs.pop(argname)
+            if value_processor:
+                value = value_processor(value)
+
+            for t in types:
+                if isinstance(value, t):
+                    if force_list and not isinstance(value, list):
+                        return [value], uvalue
+                    return value, uvalue
+            raise MesonException(f"{argname} field value {value} is not valid,"
+                                 f" valid types are {types}")
+        except KeyError:
+            if mandatory:
+                raise MesonException(f"{argname} mandatory field not found")
+
+            if default is not None:
+                return default, default
+
+        return None, None
+
+    def add_extension_paths(self, paths: T.Union[T.List[str], T.Set[str]]) -> None:
+        for path in paths:
+            if path in self._extra_extension_paths:
+                continue
+
+            self._extra_extension_paths.add(path)
+            self.cmd.extend(["--extra-extension-path", path])
+
+    def replace_dirs_in_string(self, string: str) -> str:
+        return string.replace("@SOURCE_ROOT@", self.sourcedir).replace("@BUILD_ROOT@", self.builddir)
+
+    def process_gi_c_source_roots(self) -> None:
+        if self.hotdoc.run_hotdoc(['--has-extension=gi-extension']) != 0:
+            return
+
+        value = self.kwargs.pop('gi_c_source_roots')
+        value.extend([
+            os.path.join(self.sourcedir, self.state.root_subdir),
+            os.path.join(self.builddir, self.state.root_subdir)
+        ])
+
+        self.cmd += ['--gi-c-source-roots'] + value
+
+    def process_dependencies(self, deps: T.List[T.Union[Dependency, build.StaticLibrary, build.SharedLibrary, CustomTarget, CustomTargetIndex]]) -> T.List[str]:
+        cflags = set()
+        for dep in mesonlib.listify(ensure_list(deps)):
+            if isinstance(dep, InternalDependency):
+                inc_args = self.state.get_include_args(dep.include_directories)
+                cflags.update([self.replace_dirs_in_string(x)
+                               for x in inc_args])
+                cflags.update(self.process_dependencies(dep.libraries))
+                cflags.update(self.process_dependencies(dep.sources))
+                cflags.update(self.process_dependencies(dep.ext_deps))
+            elif isinstance(dep, Dependency):
+                cflags.update(dep.get_compile_args())
+            elif isinstance(dep, (build.StaticLibrary, build.SharedLibrary)):
+                self.extra_depends.append(dep)
+                for incd in dep.get_include_dirs():
+                    cflags.update(incd.get_incdirs())
+            elif isinstance(dep, HotdocTarget):
+                # Recurse in hotdoc target dependencies
+                self.process_dependencies(dep.get_target_dependencies())
+                self._subprojects.extend(dep.subprojects)
+                self.process_dependencies(dep.subprojects)
+                self.include_paths.add(os.path.join(self.builddir, dep.hotdoc_conf.subdir))
+                self.cmd += ['--extra-assets=' + p for p in dep.extra_assets]
+                self.add_extension_paths(dep.extra_extension_paths)
+            elif isinstance(dep, (CustomTarget, build.BuildTarget)):
+                self.extra_depends.append(dep)
+            elif isinstance(dep, CustomTargetIndex):
+                self.extra_depends.append(dep.target)
+
+        return [f.strip('-I') for f in cflags]
+
+    def process_extra_assets(self) -> None:
+        self._extra_assets = self.kwargs.pop('extra_assets')
+
+        for assets_path in self._extra_assets:
+            self.cmd.extend(["--extra-assets", assets_path])
+
+    def process_subprojects(self) -> None:
+        value = self.kwargs.pop('subprojects')
+
+        self.process_dependencies(value)
+        self._subprojects.extend(value)
+
+    def flatten_config_command(self) -> T.List[str]:
+        cmd = []
+        for arg in mesonlib.listify(self.cmd, flatten=True):
+            if isinstance(arg, File):
+                arg = arg.absolute_path(self.state.environment.get_source_dir(),
+                                        self.state.environment.get_build_dir())
+            elif isinstance(arg, build.IncludeDirs):
+                for inc_dir in arg.get_incdirs():
+                    cmd.append(os.path.join(self.sourcedir, arg.get_curdir(), inc_dir))
+                    cmd.append(os.path.join(self.builddir, arg.get_curdir(), inc_dir))
+
+                continue
+            elif isinstance(arg, (build.BuildTarget, CustomTarget)):
+                self.extra_depends.append(arg)
+                arg = self.interpreter.backend.get_target_filename_abs(arg)
+            elif isinstance(arg, CustomTargetIndex):
+                self.extra_depends.append(arg.target)
+                arg = self.interpreter.backend.get_target_filename_abs(arg)
+
+            cmd.append(arg)
+
+        return cmd
+
+    def generate_hotdoc_config(self) -> None:
+        cwd = os.path.abspath(os.curdir)
+        ncwd = os.path.join(self.sourcedir, self.subdir)
+        mlog.log('Generating Hotdoc configuration for: ', mlog.bold(self.name))
+        os.chdir(ncwd)
+        if self.hotdoc.run_hotdoc(self.flatten_config_command()) != 0:
+            raise MesonException('hotdoc failed to configure')
+        os.chdir(cwd)
+
+    def ensure_file(self, value: T.Union[str, File, CustomTarget, CustomTargetIndex]) -> T.Union[File, CustomTarget, CustomTargetIndex]:
+        if isinstance(value, list):
+            res = []
+            for val in value:
+                res.append(self.ensure_file(val))
+            return res
+
+        if isinstance(value, str):
+            return File.from_source_file(self.sourcedir, self.subdir, value)
+
+        return value
+
+    def ensure_dir(self, value: str) -> str:
+        if os.path.isabs(value):
+            _dir = value
+        else:
+            _dir = os.path.join(self.sourcedir, self.subdir, value)
+
+        if not os.path.isdir(_dir):
+            raise InvalidArguments(f'"{_dir}" is not a directory.')
+
+        return os.path.relpath(_dir, os.path.join(self.builddir, self.subdir))
+
+    def check_forbidden_args(self) -> None:
+        for arg in ['conf_file']:
+            if arg in self.kwargs:
+                raise InvalidArguments(f'Argument "{arg}" is forbidden.')
+
+    def make_targets(self) -> T.Tuple[HotdocTarget, mesonlib.ExecutableSerialisation]:
+        self.check_forbidden_args()
+        self.process_known_arg("--index", value_processor=self.ensure_file)
+        self.process_known_arg("--project-version")
+        self.process_known_arg("--sitemap", value_processor=self.ensure_file)
+        self.process_known_arg("--html-extra-theme", value_processor=self.ensure_dir)
+        self.include_paths.update(self.ensure_dir(v) for v in self.kwargs.pop('include_paths'))
+        self.process_known_arg('--c-include-directories', argname="dependencies", value_processor=self.process_dependencies)
+        self.process_gi_c_source_roots()
+        self.process_extra_assets()
+        self.add_extension_paths(self.kwargs.pop('extra_extension_paths'))
+        self.process_subprojects()
+        self.extra_depends.extend(self.kwargs.pop('depends'))
+
+        install = self.kwargs.pop('install')
+        self.process_extra_args()
+
+        fullname = self.name + '-doc'
+        hotdoc_config_name = fullname + '.json'
+        hotdoc_config_path = os.path.join(
+            self.builddir, self.subdir, hotdoc_config_name)
+        with open(hotdoc_config_path, 'w', encoding='utf-8') as f:
+            f.write('{}')
+
+        self.cmd += ['--conf-file', hotdoc_config_path]
+        self.include_paths.add(os.path.join(self.builddir, self.subdir))
+        self.include_paths.add(os.path.join(self.sourcedir, self.subdir))
+
+        depfile = os.path.join(self.builddir, self.subdir, self.name + '.deps')
+        self.cmd += ['--deps-file-dest', depfile]
+
+        for path in self.include_paths:
+            self.cmd.extend(['--include-path', path])
+
+        if self.state.environment.coredata.get_option(mesonlib.OptionKey('werror', subproject=self.state.subproject)):
+            self.cmd.append('--fatal-warnings')
+        self.generate_hotdoc_config()
+
+        target_cmd = self.build_command + ["--internal", "hotdoc"] + \
+            self.hotdoc.get_command() + ['run', '--conf-file', hotdoc_config_name] + \
+            ['--builddir', os.path.join(self.builddir, self.subdir)]
+
+        target = HotdocTarget(fullname,
+                              subdir=self.subdir,
+                              subproject=self.state.subproject,
+                              environment=self.state.environment,
+                              hotdoc_conf=File.from_built_file(
+                                  self.subdir, hotdoc_config_name),
+                              extra_extension_paths=self._extra_extension_paths,
+                              extra_assets=self._extra_assets,
+                              subprojects=self._subprojects,
+                              is_build_only_subproject=self.interpreter.coredata.is_build_only,
+                              command=target_cmd,
+                              extra_depends=self.extra_depends,
+                              outputs=[fullname],
+                              sources=[],
+                              depfile=os.path.basename(depfile),
+                              build_by_default=self.build_by_default)
+
+        install_script = None
+        if install:
+            datadir = os.path.join(self.state.get_option('prefix'), self.state.get_option('datadir'))
+            devhelp = self.kwargs.get('devhelp_activate', False)
+            if not isinstance(devhelp, bool):
+                FeatureDeprecated.single_use('hotdoc.generate_doc() devhelp_activate must be boolean', '1.1.0', self.state.subproject)
+                devhelp = False
+            if devhelp:
+                install_from = os.path.join(fullname, 'devhelp')
+                install_to = os.path.join(datadir, 'devhelp')
+            else:
+                install_from = os.path.join(fullname, 'html')
+                install_to = os.path.join(datadir, 'doc', self.name, 'html')
+
+            install_script = self.state.backend.get_executable_serialisation(self.build_command + [
+                "--internal", "hotdoc",
+                "--install", install_from,
+                "--docdir", install_to,
+                '--name', self.name,
+                '--builddir', os.path.join(self.builddir, self.subdir)] +
+                self.hotdoc.get_command() +
+                ['run', '--conf-file', hotdoc_config_name])
+            install_script.tag = 'doc'
+
+        return (target, install_script)
+
+
+class HotdocTargetHolder(_CustomTargetHolder['HotdocTarget']):
+    def __init__(self, target: HotdocTarget, interp: Interpreter):
+        super().__init__(target, interp)
+        self.methods.update({'config_path': self.config_path_method})
+
+    @noPosargs
+    @noKwargs
+    def config_path_method(self, *args: T.Any, **kwargs: T.Any) -> str:
+        conf = self.held_object.hotdoc_conf.absolute_path(self.interpreter.environment.source_dir,
+                                                          self.interpreter.environment.build_dir)
+        return conf
+
+
+class HotdocTarget(CustomTarget):
+    def __init__(self, name: str, subdir: str, subproject: str, hotdoc_conf: File,
+                 extra_extension_paths: T.Set[str], extra_assets: T.List[str],
+                 subprojects: T.List['HotdocTarget'], environment: Environment,
+                 is_build_only_subproject: bool, **kwargs: T.Any):
+        super().__init__(name, subdir, subproject, environment, **kwargs, build_only_subproject=is_build_only_subproject, absolute_paths=True)
+        self.hotdoc_conf = hotdoc_conf
+        self.extra_extension_paths = extra_extension_paths
+        self.extra_assets = extra_assets
+        self.subprojects = subprojects
+
+    def __getstate__(self) -> dict:
+        # Make sure we do not try to pickle subprojects
+        res = self.__dict__.copy()
+        res['subprojects'] = []
+
+        return res
+
+
+class HotDocModule(ExtensionModule):
+
+    INFO = ModuleInfo('hotdoc', '0.48.0')
+
+    def __init__(self, interpreter: Interpreter):
+        super().__init__(interpreter)
+        self.hotdoc = HotdocExternalProgram('hotdoc')
+        if not self.hotdoc.found():
+            raise MesonException('hotdoc executable not found')
+        version = self.hotdoc.get_version(interpreter)
+        if not mesonlib.version_compare(version, f'>={MIN_HOTDOC_VERSION}'):
+            raise MesonException(f'hotdoc {MIN_HOTDOC_VERSION} required but not found.)')
+
+        self.methods.update({
+            'has_extensions': self.has_extensions,
+            'generate_doc': self.generate_doc,
+        })
+
+    @noKwargs
+    @typed_pos_args('hotdoc.has_extensions', varargs=str, min_varargs=1)
+    def has_extensions(self, state: ModuleState, args: T.Tuple[T.List[str]], kwargs: TYPE_kwargs) -> bool:
+        return self.hotdoc.run_hotdoc([f'--has-extension={extension}' for extension in args[0]]) == 0
+
+    @typed_pos_args('hotdoc.generate_doc', str)
+    @typed_kwargs(
+        'hotdoc.generate_doc',
+        KwargInfo('sitemap', file_types, required=True),
+        KwargInfo('index', file_types, required=True),
+        KwargInfo('project_version', str, required=True),
+        KwargInfo('html_extra_theme', (str, NoneType)),
+        KwargInfo('include_paths', ContainerTypeInfo(list, str), listify=True, default=[]),
+        # --c-include-directories
+        KwargInfo(
+            'dependencies',
+            ContainerTypeInfo(list, (Dependency, build.StaticLibrary, build.SharedLibrary,
+                                     CustomTarget, CustomTargetIndex)),
+            listify=True,
+            default=[],
+        ),
+        KwargInfo(
+            'depends',
+            ContainerTypeInfo(list, (CustomTarget, CustomTargetIndex)),
+            listify=True,
+            default=[],
+            since='0.64.1',
+        ),
+        KwargInfo('gi_c_source_roots', ContainerTypeInfo(list, str), listify=True, default=[]),
+        KwargInfo('extra_assets', ContainerTypeInfo(list, str), listify=True, default=[]),
+        KwargInfo('extra_extension_paths', ContainerTypeInfo(list, str), listify=True, default=[]),
+        KwargInfo('subprojects', ContainerTypeInfo(list, HotdocTarget), listify=True, default=[]),
+        KwargInfo('install', bool, default=False),
+        allow_unknown=True
+    )
+    def generate_doc(self, state: ModuleState, args: T.Tuple[str], kwargs: GenerateDocKwargs) -> ModuleReturnValue:
+        project_name = args[0]
+        if any(isinstance(x, (CustomTarget, CustomTargetIndex)) for x in kwargs['dependencies']):
+            FeatureDeprecated.single_use('hotdoc.generate_doc dependencies argument with custom_target',
+                                         '0.64.1', state.subproject, 'use `depends`', state.current_node)
+        builder = HotdocTargetBuilder(project_name, state, self.hotdoc, self.interpreter, kwargs)
+        target, install_script = builder.make_targets()
+        targets: T.List[T.Union[HotdocTarget, mesonlib.ExecutableSerialisation]] = [target]
+        if install_script:
+            targets.append(install_script)
+
+        return ModuleReturnValue(target, targets)
+
+
+def initialize(interpreter: Interpreter) -> HotDocModule:
+    mod = HotDocModule(interpreter)
+    mod.interpreter.append_holder_map(HotdocTarget, HotdocTargetHolder)
+    return mod