diff --git a/find-modules/rules_engine.py b/find-modules/rules_engine.py index 25c65a5..88cb277 100755 --- a/find-modules/rules_engine.py +++ b/find-modules/rules_engine.py @@ -1,996 +1,996 @@ #!/usr/bin/env python # # Copyright 2016 by Shaheed Haque (srhaque@theiet.org) # Copyright 2016 Stephen Kelly # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # # 1. Redistributions of source code must retain the copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # 3. The name of the author may not be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # """SIP file generation rules engine.""" from __future__ import print_function from abc import * import argparse import gettext import inspect import logging import os import re import sys import textwrap import traceback from copy import deepcopy from clang.cindex import CursorKind from clang.cindex import AccessSpecifier class HelpFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter): pass logger = logging.getLogger(__name__) gettext.install(__name__) _SEPARATOR = "\x00" def _parents(container): parents = [] parent = container.semantic_parent while parent and parent.kind != CursorKind.TRANSLATION_UNIT: parents.append(parent.spelling) parent = parent.semantic_parent if parents: parents = "::".join(reversed(parents)) else: parents = os.path.basename(container.translation_unit.spelling) return parents class Rule(object): def __init__(self, db, rule_number, fn, pattern_zip): # # Derive a useful name for diagnostic purposes. # caller = os.path.basename(inspect.stack()[3][1]) self.name = "{}:{}[{}],{}".format(caller, type(db).__name__, rule_number, fn.__name__) self.rule_number = rule_number self.fn = fn self.usage = 0 try: groups = ["(?P<{}>{})".format(name, pattern) for pattern, name in pattern_zip] groups = _SEPARATOR.join(groups) # # We'll use re.match to anchor the start of the match, and so need a $ to anchor the end. # self.matcher = re.compile(groups + "$") except Exception as e: groups = ["{} '{}'".format(name, pattern) for pattern, name in pattern_zip] groups = ", ".join(groups) raise RuntimeError(_("Bad {}: {}: {}").format(self, groups, e)) def match(self, candidate): return self.matcher.match(candidate) def trace_result(self, parents, item, original, modified): """ Record any modification both in the log and the returned result. If a rule fired, but caused no modification, that is logged. :return: Modifying rule or None. """ fqn = parents + "::" + original["name"] + "[" + str(item.extent.start.line) + "]" return self._trace_result(fqn, original, modified) def _trace_result(self, fqn, original, modified): """ Record any modification both in the log and the returned result. If a rule fired, but caused no modification, that is logged. :return: Modifying rule or None. """ if not modified["name"]: logger.debug(_("Rule {} suppressed {}, {}").format(self, fqn, original)) else: delta = False for k, v in original.items(): if v != modified[k]: delta = True break if delta: logger.debug(_("Rule {} modified {}, {}->{}").format(self, fqn, original, modified)) else: logger.warn(_("Rule {} did not modify {}, {}").format(self, fqn, original)) return None return self def __str__(self): return self.name class AbstractCompiledRuleDb(object): __metaclass__ = ABCMeta def __init__(self, db, parameter_names): self.db = db self.compiled_rules = [] for i, raw_rule in enumerate(db()): if len(raw_rule) != len(parameter_names) + 1: raise RuntimeError(_("Bad raw rule {}: {}: {}").format(db.__name__, raw_rule, parameter_names)) z = zip(raw_rule[:-1], parameter_names) self.compiled_rules.append(Rule(self, i, raw_rule[-1], z)) self.candidate_formatter = _SEPARATOR.join(["{}"] * len(parameter_names)) def _match(self, *args): candidate = self.candidate_formatter.format(*args) for rule in self.compiled_rules: matcher = rule.match(candidate) if matcher: # # Only use the first matching rule. # rule.usage += 1 return matcher, rule return None, None @abstractmethod def apply(self, *args): raise NotImplemented(_("Missing subclass")) def dump_usage(self, fn): """ Dump the usage counts.""" for rule in self.compiled_rules: fn(str(rule), rule.usage) class ContainerRuleDb(AbstractCompiledRuleDb): """ THE RULES FOR CONTAINERS. - These are used to customise the behaviour of the SIP generator by allowing + These are used to customize the behaviour of the SIP generator by allowing the declaration for any container (class, namespace, struct, union) to be - customised, for example to add SIP compiler annotations. + customized, for example to add SIP compiler annotations. Each entry in the raw rule database must be a list with members as follows: 0. A regular expression which matches the fully-qualified name of the "container" enclosing the container. 1. A regular expression which matches the container name. 2. A regular expression which matches any template parameters. 3. A regular expression which matches the container declaration. 4. A regular expression which matches any base specifiers. 5. A function. In use, the database is walked in order from the first entry. If the regular expressions are matched, the function is called, and no further entries are walked. The function is called with the following contract: def container_xxx(container, sip, matcher): ''' Return a modified declaration for the given container. :param container: The clang.cindex.Cursor for the container. :param sip: A dict with the following keys: name The name of the container. template_parameters Any template parameters. decl The declaration. base_specifiers Any base specifiers. body The body, less the outer pair of braces. annotations Any SIP annotations. :param matcher: The re.Match object. This contains named groups corresponding to the key names above EXCEPT body and annotations. :return: An updated set of sip.xxx values. Setting sip.name to the empty string will cause the container to be suppressed. ''' :return: The compiled form of the rules. """ def __init__(self, db): super(ContainerRuleDb, self).__init__(db, ["parents", "container", "template_parameters", "decl", "base_specifiers"]) def apply(self, container, sip): """ Walk over the rules database for containers, applying the first matching transformation. :param container: The clang.cindex.Cursor for the container. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ parents = _parents(container) matcher, rule = self._match(parents, sip["name"], ", ".join(sip["template_parameters"]), sip["decl"], ", ".join(sip["base_specifiers"])) if matcher: before = deepcopy(sip) rule.fn(container, sip, matcher) return rule.trace_result(parents, container, before, sip) return None class ForwardDeclarationRuleDb(AbstractCompiledRuleDb): """ THE RULES FOR FORWARD DECLARATIONS. - These are used to customise the behaviour of the SIP generator by allowing + These are used to customize the behaviour of the SIP generator by allowing the forward declaration for any container (class, struct, union) to be - customised, for example to add SIP compiler annotations. + customized, for example to add SIP compiler annotations. Each entry in the raw rule database must be a list with members as follows: 0. A regular expression which matches the fully-qualified name of the "container" enclosing the container. 1. A regular expression which matches the container name. 2. A regular expression which matches any template parameters. 3. A function. In use, the database is walked in order from the first entry. If the regular expressions are matched, the function is called, and no further entries are walked. The function is called with the following contract: def declaration_xxx(container, sip, matcher): ''' Return a modified declaration for the given container. :param container: The clang.cindex.Cursor for the container. :param sip: A dict with the following keys: name The name of the container. template_parameters Any template parameters. annotations Any SIP annotations. :param matcher: The re.Match object. This contains named groups corresponding to the key names above EXCEPT body and annotations. :return: An updated set of sip.xxx values. Setting sip.name to the empty string will cause the container to be suppressed. ''' :return: The compiled form of the rules. """ def __init__(self, db): super(ForwardDeclarationRuleDb, self).__init__(db, ["parents", "container", "template_parameters"]) def apply(self, container, sip): """ Walk over the rules database for containers, applying the first matching transformation. :param container: The clang.cindex.Cursor for the container. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ parents = _parents(container) matcher, rule = self._match(parents, sip["name"], ", ".join(sip["template_parameters"])) if matcher: before = deepcopy(sip) rule.fn(container, sip, matcher) return rule.trace_result(parents, container, before, sip) return None class FunctionRuleDb(AbstractCompiledRuleDb): """ THE RULES FOR FUNCTIONS. - These are used to customise the behaviour of the SIP generator by allowing - the declaration for any function to be customised, for example to add SIP + These are used to customize the behaviour of the SIP generator by allowing + the declaration for any function to be customized, for example to add SIP compiler annotations. Each entry in the raw rule database must be a list with members as follows: 0. A regular expression which matches the fully-qualified name of the "container" enclosing the function. 1. A regular expression which matches the function name. 2. A regular expression which matches any template parameters. 3. A regular expression which matches the function result. 4. A regular expression which matches the function parameters (e.g. "int a, void *b" for "int foo(int a, void *b)"). 5. A function. In use, the database is walked in order from the first entry. If the regular expressions are matched, the function is called, and no further entries are walked. The function is called with the following contract: def function_xxx(container, function, sip, matcher): ''' Return a modified declaration for the given function. :param container: The clang.cindex.Cursor for the container. :param function: The clang.cindex.Cursor for the function. :param sip: A dict with the following keys: name The name of the function. template_parameters Any template parameters. fn_result Result, if not a constructor. parameters The parameters. prefix Leading keyworks ("static"). Separated by space, ends with a space. suffix Trailing keywords ("const"). Separated by space, starts with space. annotations Any SIP annotations. :param matcher: The re.Match object. This contains named groups corresponding to the key names above EXCEPT annotations. :return: An updated set of sip.xxx values. Setting sip.name to the empty string will cause the container to be suppressed. ''' :return: The compiled form of the rules. """ def __init__(self, db): super(FunctionRuleDb, self).__init__(db, ["container", "function", "template_parameters", "fn_result", "parameters"]) def apply(self, container, function, sip): """ Walk over the rules database for functions, applying the first matching transformation. :param container: The clang.cindex.Cursor for the container. :param function: The clang.cindex.Cursor for the function. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ parents = _parents(function) matcher, rule = self._match(parents, sip["name"], ", ".join(sip["template_parameters"]), sip["fn_result"], ", ".join(sip["parameters"])) if matcher: sip.setdefault("code", "") before = deepcopy(sip) rule.fn(container, function, sip, matcher) return rule.trace_result(parents, function, before, sip) return None class ParameterRuleDb(AbstractCompiledRuleDb): """ THE RULES FOR FUNCTION PARAMETERS. - These are used to customise the behaviour of the SIP generator by allowing - the declaration for any parameter in any function to be customised, for + These are used to customize the behaviour of the SIP generator by allowing + the declaration for any parameter in any function to be customized, for example to add SIP compiler annotations. Each entry in the raw rule database must be a list with members as follows: 0. A regular expression which matches the fully-qualified name of the "container" enclosing the function enclosing the parameter. 1. A regular expression which matches the function name enclosing the parameter. 2. A regular expression which matches the parameter name. 3. A regular expression which matches the parameter declaration (e.g. "int foo"). 4. A regular expression which matches the parameter initialiser (e.g. "Xyz:MYCONST + 42"). 5. A function. In use, the database is walked in order from the first entry. If the regular expressions are matched, the function is called, and no further entries are walked. The function is called with the following contract: def parameter_xxx(container, function, parameter, sip, init, matcher): ''' Return a modified declaration and initialiser for the given parameter. :param container: The clang.cindex.Cursor for the container. :param function: The clang.cindex.Cursor for the function. :param parameter: The clang.cindex.Cursor for the parameter. :param sip: A dict with the following keys: name The name of the function. decl The declaration. init Any initialiser. annotations Any SIP annotations. :param matcher: The re.Match object. This contains named groups corresponding to the key names above EXCEPT annotations. :return: An updated set of sip.xxx values. ''' :return: The compiled form of the rules. """ def __init__(self, db): super(ParameterRuleDb, self).__init__(db, ["container", "function", "parameter", "decl", "init"]) def apply(self, container, function, parameter, sip): """ Walk over the rules database for parameters, applying the first matching transformation. :param container: The clang.cindex.Cursor for the container. :param function: The clang.cindex.Cursor for the function. :param parameter: The clang.cindex.Cursor for the parameter. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ parents = _parents(function) matcher, rule = self._match(parents, function.spelling, sip["name"], sip["decl"], sip["init"]) if matcher: sip.setdefault("code", "") before = deepcopy(sip) rule.fn(container, function, parameter, sip, matcher) return rule.trace_result(parents, parameter, before, sip) return None class TypedefRuleDb(AbstractCompiledRuleDb): """ THE RULES FOR TYPEDEFS. - These are used to customise the behaviour of the SIP generator by allowing - the declaration for any typedef to be customised, for example to add SIP + These are used to customize the behaviour of the SIP generator by allowing + the declaration for any typedef to be customized, for example to add SIP compiler annotations. Each entry in the raw rule database must be a list with members as follows: 0. A regular expression which matches the fully-qualified name of the "container" enclosing the typedef. 1. A regular expression which matches the typedef name. 2. A function. In use, the database is walked in order from the first entry. If the regular expressions are matched, the function is called, and no further entries are walked. The function is called with the following contract: def typedef_xxx(container, typedef, sip, matcher): ''' Return a modified declaration for the given function. :param container: The clang.cindex.Cursor for the container. :param typedef: The clang.cindex.Cursor for the typedef. :param sip: A dict with the following keys: name The name of the typedef. annotations Any SIP annotations. :param matcher: The re.Match object. This contains named groups corresponding to the key names above EXCEPT annotations. :return: An updated set of sip.xxx values. Setting sip.name to the empty string will cause the container to be suppressed. ''' :return: The compiled form of the rules. """ def __init__(self, db): super(TypedefRuleDb, self).__init__(db, ["container", "typedef"]) def apply(self, container, typedef, sip): """ Walk over the rules database for typedefs, applying the first matching transformation. :param container: The clang.cindex.Cursor for the container. :param typedef: The clang.cindex.Cursor for the typedef. :param sip: The SIP dict. """ parents = _parents(typedef) matcher, rule = self._match(parents, sip["name"]) if matcher: before = deepcopy(sip) rule.fn(container, typedef, sip, matcher) return rule.trace_result(parents, typedef, before, sip) return None class VariableRuleDb(AbstractCompiledRuleDb): """ THE RULES FOR VARIABLES. - These are used to customise the behaviour of the SIP generator by allowing - the declaration for any variable to be customised, for example to add SIP + These are used to customize the behaviour of the SIP generator by allowing + the declaration for any variable to be customized, for example to add SIP compiler annotations. Each entry in the raw rule database must be a list with members as follows: 0. A regular expression which matches the fully-qualified name of the "container" enclosing the variable. 1. A regular expression which matches the variable name. 2. A regular expression which matches the variable declaration (e.g. "int foo"). 3. A function. In use, the database is walked in order from the first entry. If the regular expressions are matched, the function is called, and no further entries are walked. The function is called with the following contract: def variable_xxx(container, variable, sip, matcher): ''' Return a modified declaration for the given variable. :param container: The clang.cindex.Cursor for the container. :param variable: The clang.cindex.Cursor for the variable. :param sip: A dict with the following keys: name The name of the variable. decl The declaration. annotations Any SIP annotations. :param matcher: The re.Match object. This contains named groups corresponding to the key names above EXCEPT annotations. :return: An updated set of sip.xxx values. Setting sip.name to the empty string will cause the container to be suppressed. ''' :return: The compiled form of the rules. """ def __init__(self, db): super(VariableRuleDb, self).__init__(db, ["container", "variable", "decl"]) def apply(self, container, variable, sip): """ Walk over the rules database for variables, applying the first matching transformation. :param container: The clang.cindex.Cursor for the container. :param variable: The clang.cindex.Cursor for the variable. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ parents = _parents(variable) matcher, rule = self._match(parents, sip["name"], sip["decl"]) if matcher: sip.setdefault("code", "") before = deepcopy(sip) rule.fn(container, variable, sip, matcher) return rule.trace_result(parents, variable, before, sip) return None class AbstractCompiledCodeDb(object): __metaclass__ = ABCMeta def __init__(self, db): caller = os.path.basename(inspect.stack()[2][1]) self.name = "{}:{}".format(caller, type(self).__name__) self.db = db @abstractmethod def apply(self, function, sip): raise NotImplemented(_("Missing subclass")) def trace_result(self, parents, item, original, modified): """ Record any modification both in the log and the returned result. If a rule fired, but caused no modification, that is logged. :return: Modifying rule or None. """ fqn = parents + "::" + original["name"] + "[" + str(item.extent.start.line) + "]" self._trace_result(fqn, original, modified) def _trace_result(self, fqn, original, modified): """ Record any modification both in the log and the returned result. If a rule fired, but caused no modification, that is logged. :return: Modifying rule or None. """ if not modified["name"]: logger.debug(_("Rule {} suppressed {}, {}").format(self, fqn, original)) else: delta = False for k, v in original.items(): if v != modified[k]: delta = True break if delta: logger.debug(_("Rule {} modified {}, {}->{}").format(self, fqn, original, modified)) else: logger.warn(_("Rule {} did not modify {}, {}").format(self, fqn, original)) return None return self @abstractmethod def dump_usage(self, fn): raise NotImplemented(_("Missing subclass")) def __str__(self): return self.name class MethodCodeDb(AbstractCompiledCodeDb): """ THE RULES FOR INJECTING METHOD-RELATED CODE (such as %MethodCode, %VirtualCatcherCode, %VirtualCallCode and other method-level directives). - These are used to customise the behaviour of the SIP generator by allowing + These are used to customize the behaviour of the SIP generator by allowing method-level code injection. The raw rule database must be an outer dictionary as follows: 0. Each key is the fully-qualified name of a "container" enclosing methods. 1. Each value is an inner dictionary, each of whose keys is the name of a method. Each inner dictionary has entries which update the declaration as follows: "name": Optional string. If present, overrides the name of the method. "parameters": Optional list. If present, update the argument list. "fn_result": Optional string. If present, update the return type. "code": Required. Either a string, with the %XXXCode content, or a callable. In use, the database is directly indexed by "container" and then method name. If "code" entry is a string, then the other optional keys are interpreted as above. If "code" is a callable, it is called with the following contract: def methodcode_xxx(function, sip, entry): ''' Return a modified declaration for the given function. :param function: The clang.cindex.Cursor for the function. :param sip: A dict with keys as for function rules and (string) "code" keys described above. :param entry: The inner dictionary entry. :return: An updated set of sip.xxx values. ''' :return: The compiled form of the rules. """ __metaclass__ = ABCMeta def __init__(self, db): super(MethodCodeDb, self).__init__(db) for k, v in self.db.items(): for l in v.keys(): v[l]["usage"] = 0 def _get(self, item, name): parents = _parents(item) entries = self.db.get(parents, None) if not entries: return None entry = entries.get(name, None) if not entry: return None entry["usage"] += 1 return entry def apply(self, function, sip): """ Walk over the code database for functions, applying the first matching transformation. :param function: The clang.cindex.Cursor for the function. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ entry = self._get(function, sip["name"]) sip.setdefault("code", "") if entry: before = deepcopy(sip) if callable(entry["code"]): fn = entry["code"] fn_file = os.path.basename(inspect.getfile(fn)) trace = "// Generated (by {}:{}): {}\n".format(fn_file, fn.__name__, {k:v for (k,v) in entry.items() if k != "code"}) fn(function, sip, entry) else: trace = "// Inserted (by {}:{}): {}\n".format(_parents(function), function.spelling, {k:v for (k,v) in entry.items() if k != "code"}) sip["code"] = entry["code"] sip["parameters"] = entry.get("parameters", sip["parameters"]) sip["fn_result"] = entry.get("fn_result", sip["fn_result"]) # # Fetch/format the code. # sip["code"] = trace + textwrap.dedent(sip["code"]).strip() + "\n" return self.trace_result(_parents(function), function, before, sip) return None def dump_usage(self, fn): """ Dump the usage counts.""" for k in sorted(self.db.keys()): vk = self.db[k] for l in sorted(vk.keys()): vl = vk[l] fn(str(self) + " for " + k + "," + l, vl["usage"]) class ModuleCodeDb(AbstractCompiledCodeDb): """ THE RULES FOR INJECTING MODULE-RELATED CODE (such as %ExportedHeaderCode, %ModuleCode, %ModuleHeaderCode or other module-level directives). - These are used to customise the behaviour of the SIP generator by allowing + These are used to customize the behaviour of the SIP generator by allowing module-level code injection. The raw rule database must be a dictionary as follows: 0. Each key is the basename of a header file. 1. Each value has entries which update the declaration as follows: "code": Required. Either a string, with the %XXXCode content, or a callable. If "code" is a callable, it is called with the following contract: def module_xxx(filename, sip, entry): ''' Return a string to insert for the file. :param filename: The filename. :param sip: A dict with the key "name" for the filename, "decl" for the module body plus the "code" key described above. :param entry: The dictionary entry. :return: A string. ''' :return: The compiled form of the rules. """ __metaclass__ = ABCMeta def __init__(self, db): super(ModuleCodeDb, self).__init__(db) # # Add a usage count and other diagnostic support for each item in the database. # for k, v in self.db.items(): v["usage"] = 0 def _get(self, filename): # # Lookup for an actual hit. # entry = self.db.get(filename, None) if not entry: return None entry["usage"] += 1 return entry def apply(self, filename, sip): """ Walk over the code database for modules, applying the first matching transformation. :param filename: The file for the module. :param sip: The SIP dict (may be modified on return). :return: Modifying rule or None (even if a rule matched, it may not modify things). """ entry = self._get(filename) sip.setdefault("code", "") if entry: before = deepcopy(sip) if callable(entry["code"]): fn = entry["code"] fn_file = os.path.basename(inspect.getfile(fn)) trace = "\n// Generated (by {}:{}): {}".format(fn_file, fn.__name__, {k:v for (k,v) in entry.items() if k != "code"}) fn(filename, sip, entry) sip["code"] = trace + sip["code"] else: sip["code"] = entry["code"] # # Fetch/format the code. # sip["code"] = textwrap.dedent(sip["code"]).strip() + "\n" fqn = filename + "::" + before["name"] self._trace_result(fqn, before, sip) def dump_usage(self, fn): """ Dump the usage counts.""" for k in sorted(self.db.keys()): v = self.db[k] fn(str(self) + " for " + k, v["usage"]) class RuleSet(object): """ To implement your own binding, create a subclass of RuleSet, also called RuleSet in your own Python module. Your subclass will expose the raw rules along with other ancilliary data exposed through the subclass methods. You then simply run the SIP generation and SIP compilation programs passing in the name of your rules file """ __metaclass__ = ABCMeta @abstractmethod def container_rules(self): """ Return a compiled list of rules for containers. :return: A ContainerRuleDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def forward_declaration_rules(self): """ Return a compiled list of rules for containers. :return: A ForwardDeclarationRuleDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def function_rules(self): """ Return a compiled list of rules for functions. :return: A FunctionRuleDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def parameter_rules(self): """ Return a compiled list of rules for function parameters. :return: A ParameterRuleDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def typedef_rules(self): """ Return a compiled list of rules for typedefs. :return: A TypedefRuleDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def variable_rules(self): """ Return a compiled list of rules for variables. :return: A VariableRuleDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def methodcode_rules(self): """ Return a compiled list of rules for method-related code. :return: A MethodCodeDb instance """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def modulecode_rules(self): """ Return a compiled list of rules for module-related code. :return: A ModuleCodeDb instance """ raise NotImplemented(_("Missing subclass implementation")) def dump_unused(self): """Usage statistics, to identify unused rules.""" def dumper(rule, usage): if usage: logger.info(_("Rule {} used {} times".format(rule, usage))) else: logger.warn(_("Rule {} was not used".format(rule))) for db in [self.container_rules(), self.forward_declaration_rules(), self.function_rules(), self.parameter_rules(), self.typedef_rules(), self.variable_rules(), self.methodcode_rules(), self.modulecode_rules()]: db.dump_usage(dumper) @abstractmethod def methodcode(self, container, function): """ Lookup %MethodCode. """ raise NotImplemented(_("Missing subclass implementation")) @abstractmethod def modulecode(self, filename): """ Lookup %ModuleCode and friends. """ raise NotImplemented(_("Missing subclass implementation")) def container_discard(container, sip, matcher): sip["name"] = "" def function_discard(container, function, sip, matcher): sip["name"] = "" def parameter_transfer_to_parent(container, function, parameter, sip, matcher): if function.is_static_method(): sip["annotations"].add("Transfer") else: sip["annotations"].add("TransferThis") def param_rewrite_mode_t_as_int(container, function, parameter, sip, matcher): sip["decl"] = sip["decl"].replace("mode_t", "unsigned int") def return_rewrite_mode_t_as_int(container, function, sip, matcher): sip["fn_result"] = "unsigned int" def variable_discard(container, variable, sip, matcher): sip["name"] = "" def parameter_strip_class_enum(container, function, parameter, sip, matcher): sip["decl"] = sip["decl"].replace("class ", "").replace("enum ", "") def function_discard_impl(container, function, sip, matcher): if function.extent.start.column == 1: sip["name"] = "" def typedef_discard(container, typedef, sip, matcher): sip["name"] = "" def discard_QSharedData_base(container, sip, matcher): sip["base_specifiers"].remove("QSharedData") def mark_forward_declaration_external(container, sip, matcher): sip["annotations"].add("External") def container_mark_abstract(container, sip, matcher): sip["annotations"].add("Abstract") def rules(project_rules): """ Constructor. :param project_rules: The rules file for the project. """ import imp imp.load_source("project_rules", project_rules) # # Statically prepare the rule logic. This takes the rules provided by the user and turns them into code. # return getattr(sys.modules["project_rules"], "RuleSet")() diff --git a/find-modules/sip_generator.py b/find-modules/sip_generator.py index 20e55ce..b521e6c 100644 --- a/find-modules/sip_generator.py +++ b/find-modules/sip_generator.py @@ -1,819 +1,819 @@ #!/usr/bin/env python # # Copyright 2016 by Shaheed Haque (srhaque@theiet.org) # Copyright 2016 by Stephen Kelly (steveire@gmail.com) # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # # 1. Redistributions of source code must retain the copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # 3. The name of the author may not be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # """SIP file generator for PyQt.""" from __future__ import print_function import argparse import gettext import inspect import logging import os import re import sys import traceback from clang import cindex from clang.cindex import AccessSpecifier, AvailabilityKind, CursorKind, SourceRange, StorageClass, TokenKind, TypeKind, TranslationUnit import rules_engine class HelpFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter): pass logger = logging.getLogger(__name__) gettext.install(__name__) EXPR_KINDS = [ CursorKind.UNEXPOSED_EXPR, CursorKind.CONDITIONAL_OPERATOR, CursorKind.UNARY_OPERATOR, CursorKind.BINARY_OPERATOR, CursorKind.INTEGER_LITERAL, CursorKind.FLOATING_LITERAL, CursorKind.STRING_LITERAL, CursorKind.CXX_BOOL_LITERAL_EXPR, CursorKind.CXX_STATIC_CAST_EXPR, CursorKind.DECL_REF_EXPR ] TEMPLATE_KINDS = [ CursorKind.TYPE_REF, CursorKind.TEMPLATE_REF, CursorKind.NAMESPACE_REF ] + EXPR_KINDS def clang_diagnostic_to_logging_diagnostic(lvl): """ The diagnostic levels in cindex.py are Ignored = 0 Note = 1 Warning = 2 Error = 3 Fatal = 4 and the leves in the python logging module are NOTSET 0 DEBUG 10 INFO 20 WARNING 30 ERROR 40 CRITICAL 50 """ return (logging.NOTSET, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL)[lvl] def diagnostic_word(lvl): return ("", "info", "warning", "error", "fatality")[lvl] class SipGenerator(object): def __init__(self, project_rules, compile_flags, verbose=False, dump_includes=False, dump_privates=False): """ Constructor. :param project_rules: The rules for the file. :param compile_flags: The compile flags for the file. :param dump_includes: Turn on diagnostics for include files. :param dump_privates: Turn on diagnostics for omitted private items. """ self.rules = project_rules self.compile_flags = compile_flags self.verbose = verbose self.dump_includes = dump_includes self.dump_privates = dump_privates self.diagnostics = set() self.tu = None self.unpreprocessed_source = None @staticmethod def describe(cursor, text=None): if not text: text = cursor.spelling return "{} on line {} '{}'".format(cursor.kind.name, cursor.extent.start.line, text) def create_sip(self, h_file, include_filename): """ Actually convert the given source header file into its SIP equivalent. :param h_file: The source (header) file of interest. :param include_filename: The (header) to generate in the sip file. """ # # Read in the original file. # source = h_file self.unpreprocessed_source = [] with open(source, "rb") as f: for line in f: self.unpreprocessed_source.append(line) index = cindex.Index.create() self.tu = index.parse(source, ["-x", "c++"] + self.compile_flags) for diag in self.tu.diagnostics: # # We expect to be run over hundreds of files. Any parsing issues are likely to be very repetitive. # So, to avoid bothering the user, we suppress duplicates. # loc = diag.location msg = "{}:{}[{}] {}".format(loc.file, loc.line, loc.column, diag.spelling) if (diag.spelling == "#pragma once in main file"): continue if msg in self.diagnostics: continue self.diagnostics.add(msg) logger.log(clang_diagnostic_to_logging_diagnostic(diag.severity), "Parse {}: {}".format(diagnostic_word(diag.severity), msg)) if self.dump_includes: for include in sorted(set(self.tu.get_includes())): logger.debug(_("Used includes {}").format(include.include.name)) # # Run through the top level children in the translation unit. # body = self._container_get(self.tu.cursor, -1, h_file, include_filename) return body, self.tu.get_includes def skippable_attribute(self, parent, member, text, sip): """ We don't seem to have access to the __attribute__(())s, but at least we can look for stuff we care about. :param member: The attribute. :param text: The raw source corresponding to the region of member. """ if member.kind != CursorKind.VISIBILITY_ATTR: return False if member.spelling == "hidden": if self.dump_privates: logger.debug("Ignoring private {}".format(SipGenerator.describe(parent))) sip["name"] = "" return True return False def _container_get(self, container, level, h_file, include_filename): """ Generate the (recursive) translation for a class or namespace. :param container: A class or namespace. :param h_file: Name of header file being processed. :param level: Recursion level controls indentation. :return: A string. """ if container.kind.is_translation_unit(): # # Any module-related manual code (%ExportedHeaderCode, %ModuleCode, %ModuleHeaderCode or other # module-level directives? # sip = { "name": include_filename, "decl": "" } self.rules.modulecode(include_filename, sip) body = sip["code"] else: body = "" sip = { "name": container.displayname, "annotations": set() } name = container.displayname if container.access_specifier == AccessSpecifier.PRIVATE: if self.dump_privates: logger.debug("Ignoring private {}".format(SipGenerator.describe(container))) return "" base_specifiers = [] template_type_parameters = [] had_copy_constructor = False had_deleted_copy_constructor = False; had_const_member = False for member in container.get_children(): # # Only emit items in the translation unit. # if member.location.file.name != self.tu.spelling: continue decl = "" if member.kind in [CursorKind.CXX_METHOD, CursorKind.FUNCTION_DECL, CursorKind.FUNCTION_TEMPLATE, CursorKind.CONSTRUCTOR, CursorKind.DESTRUCTOR, CursorKind.CONVERSION_FUNCTION]: decl = self._fn_get(container, member, level + 1) elif member.kind == CursorKind.ENUM_DECL: decl = self._enum_get(container, member, level + 1) + ";\n" elif member.kind == CursorKind.CXX_ACCESS_SPEC_DECL: decl = self._get_access_specifier(member, level + 1) elif member.kind == CursorKind.TYPEDEF_DECL: decl = self._typedef_get(container, member, level + 1) elif member.kind == CursorKind.CXX_BASE_SPECIFIER: # # Strip off the leading "class". Except for TypeKind.UNEXPOSED... # base_specifiers.append(member.displayname.split(None, 2)[-1]) elif member.kind == CursorKind.TEMPLATE_TYPE_PARAMETER: template_type_parameters.append(member.displayname) elif member.kind == CursorKind.TEMPLATE_NON_TYPE_PARAMETER: template_type_parameters.append(member.type.spelling + " " + member.displayname) elif member.kind in [CursorKind.VAR_DECL, CursorKind.FIELD_DECL]: had_const_member = had_const_member or member.type.is_const_qualified() decl = self._var_get(container, member, level + 1) elif member.kind in [CursorKind.NAMESPACE, CursorKind.CLASS_DECL, CursorKind.CLASS_TEMPLATE, CursorKind.CLASS_TEMPLATE_PARTIAL_SPECIALIZATION, CursorKind.STRUCT_DECL, CursorKind.UNION_DECL]: decl = self._container_get(member, level + 1, h_file, include_filename) elif member.kind in TEMPLATE_KINDS + [CursorKind.USING_DECLARATION, CursorKind.USING_DIRECTIVE, CursorKind.CXX_FINAL_ATTR]: # # Ignore: # # TEMPLATE_KINDS: Template type parameter. # CursorKind.USING_DECLARATION, CursorKind.USING_DIRECTIVE: Using? Pah! # CursorKind.CXX_FINAL_ATTR: Again, not much to be done with this. # pass else: text = self._read_source(member.extent) if self.skippable_attribute(container, member, text, sip): if not sip["name"]: return "" else: SipGenerator._report_ignoring(container, member) def is_copy_constructor(member): if member.kind != CursorKind.CONSTRUCTOR: return False numParams = 0 hasSelfType = False for child in member.get_children(): numParams += 1 if child.kind == CursorKind.PARM_DECL: paramType = child.type.spelling paramType = paramType.split("::")[-1] paramType = paramType.replace("const", "").replace("&", "").strip() hasSelfType = paramType == container.displayname return numParams == 1 and hasSelfType def has_parameter_default(parameter): for member in parameter.get_children(): if member.kind.is_expression(): return True return False def is_default_constructor(member): if member.kind != CursorKind.CONSTRUCTOR: return False numParams = 0 for parameter in member.get_children(): if (has_parameter_default(parameter)): break numParams += 1 return numParams == 0 if is_copy_constructor(member): had_copy_constructor = True # We need to generate a fake private copy constructor for deleted constructors if member.availability == AvailabilityKind.NOT_AVAILABLE and member.access_specifier != AccessSpecifier.PRIVATE: had_deleted_copy_constructor = True continue # # Discard almost anything which is private. # if member.access_specifier == AccessSpecifier.PRIVATE: if member.kind == CursorKind.CXX_ACCESS_SPEC_DECL: # # We need these because... # pass elif is_copy_constructor(member) or is_default_constructor(member): # # ...we need to pass private copy contructors to the SIP compiler. # pass else: if self.dump_privates: logger.debug("Ignoring private {}".format(SipGenerator.describe(member))) continue if decl: if self.verbose: pad = " " * ((level + 1) * 4) body += pad + "// {}\n".format(SipGenerator.describe(member)) body += decl if container.kind == CursorKind.TRANSLATION_UNIT: return body if container.kind == CursorKind.NAMESPACE: container_type = "namespace " + name elif container.kind in [CursorKind.CLASS_DECL, CursorKind.CLASS_TEMPLATE, CursorKind.CLASS_TEMPLATE_PARTIAL_SPECIALIZATION]: container_type = "class " + name elif container.kind == CursorKind.STRUCT_DECL: container_type = "struct " + name elif container.kind == CursorKind.UNION_DECL: container_type = "union " + name else: raise AssertionError( _("Unexpected container {}: {}[{}]").format(container.kind, name, container.extent.start.line)) sip["decl"] = container_type sip["template_parameters"] = template_type_parameters pad = " " * (level * 4) # # Empty containers are still useful if they provide namespaces or forward declarations. # if not body: text = self._read_source(container.extent) if not text.endswith("}"): # # Forward declaration. # modifying_rule = self.rules.forward_declaration_rules().apply(container, sip) if sip["name"]: if modifying_rule: body += "// Modified {} (by {}):\n".format(SipGenerator.describe(container), modifying_rule) if "External" in sip["annotations"]: body += pad + sip["decl"] body += " /External/;\n" else: body = pad + "// Discarded {} (by {})\n".format(SipGenerator.describe(container), "default forward declaration handling") else: body = pad + "// Discarded {} (by {})\n".format(SipGenerator.describe(container), modifying_rule) else: # # Generate private copy constructor for non-copyable types. # if (had_deleted_copy_constructor) or (had_const_member and not had_copy_constructor): body += " private:\n {}(const {} &); // Generated\n".format(name, container.type.get_canonical().spelling) # # Flesh out the SIP context for the rules engine. # sip["base_specifiers"] = base_specifiers sip["body"] = body modifying_rule = self.rules.container_rules().apply(container, sip) if sip["name"]: decl = "" if modifying_rule: decl += "// Modified {} (by {}):\n".format(SipGenerator.describe(container), modifying_rule) decl += pad + sip["decl"] if sip["base_specifiers"]: decl += ": " + ", ".join(sip["base_specifiers"]) if sip["annotations"]: decl += " /" + ",".join(sip["annotations"]) + "/" if sip["template_parameters"]: decl = pad + "template <" + ", ".join(sip["template_parameters"]) + ">\n" + decl decl += "\n" + pad + "{\n" decl += "%TypeHeaderCode\n#include <{}>\n%End\n".format(include_filename) body = decl + sip["body"] + pad + "};\n" else: body = pad + "// Discarded {} (by {})\n".format(SipGenerator.describe(container), modifying_rule) return body def _get_access_specifier(self, member, level): """ Skip access specifiers embedded in the Q_OBJECT macro. """ access_specifier_text = self._read_source(member.extent) if access_specifier_text == "Q_OBJECT": return "" pad = " " * ((level - 1) * 4) access_specifier = "" if (access_specifier_text in ("Q_SIGNALS:", "signals:", "public Q_SLOTS:", "public slots:", "protected Q_SLOTS:", "protected slots:")): access_specifier = access_specifier_text elif member.access_specifier == AccessSpecifier.PRIVATE: access_specifier = "private:" elif member.access_specifier == AccessSpecifier.PROTECTED: access_specifier = "protected:" elif member.access_specifier == AccessSpecifier.PUBLIC: access_specifier = "public:" decl = pad + access_specifier + "\n" return decl def _enum_get(self, container, enum, level): pad = " " * (level * 4) scoped = "" if enum.is_scoped_enum(): scoped = "class " decl = pad + "enum {}{} {{\n".format(scoped, enum.displayname) enumerations = [] for enum in enum.get_children(): # # Skip visibility attributes and the like. # if enum.kind == CursorKind.ENUM_CONSTANT_DECL: enumerations.append(pad + " {}".format(enum.displayname)) decl += ",\n".join(enumerations) + "\n" decl += pad + "}" return decl def _fn_get(self, container, function, level): """ Generate the translation for a function. :param container: A class or namespace. :param function: The function object. :param level: Recursion level controls indentation. :return: A string. """ if container.kind == CursorKind.TRANSLATION_UNIT and \ (function.semantic_parent.kind == CursorKind.CLASS_DECL or function.semantic_parent.kind == CursorKind.STRUCT_DECL) and \ function.is_definition(): # Skip inline methods return sip = { "name": function.spelling, } parameters = [] parameter_modifying_rules = [] template_parameters = [] for child in function.get_children(): if child.kind == CursorKind.PARM_DECL: parameter = child.displayname or "__{}".format(len(parameters)) theType = child.type.get_canonical() typeSpelling = theType.spelling if theType.kind == TypeKind.POINTER: typeSpelling = theType.get_pointee().spelling + "* " decl = "{} {}".format(typeSpelling, parameter) child_sip = { "name": parameter, "decl": decl, "init": self._fn_get_parameter_default(function, child), "annotations": set() } modifying_rule = self.rules.parameter_rules().apply(container, function, child, child_sip) if modifying_rule: parameter_modifying_rules.append("// Modified {} (by {}):\n".format(SipGenerator.describe(child), modifying_rule)) decl = child_sip["decl"] if child_sip["annotations"]: decl += " /" + ",".join(child_sip["annotations"]) + "/" if child_sip["init"]: decl += " = " + child_sip["init"] parameters.append(decl) elif child.kind in [CursorKind.COMPOUND_STMT, CursorKind.CXX_OVERRIDE_ATTR, CursorKind.MEMBER_REF, CursorKind.DECL_REF_EXPR, CursorKind.CALL_EXPR] + TEMPLATE_KINDS: # # Ignore: # # CursorKind.COMPOUND_STMT: Function body. # CursorKind.CXX_OVERRIDE_ATTR: The "override" keyword. # CursorKind.MEMBER_REF, CursorKind.DECL_REF_EXPR, CursorKind.CALL_EXPR: Constructor initialisers. # TEMPLATE_KINDS: The result type. # pass elif child.kind == CursorKind.TEMPLATE_TYPE_PARAMETER: template_parameters.append(child.displayname) elif child.kind == CursorKind.TEMPLATE_NON_TYPE_PARAMETER: template_parameters.append(child.type.spelling + " " + child.displayname) else: text = self._read_source(child.extent) if self.skippable_attribute(function, child, text, sip): if not sip["name"]: return "" else: SipGenerator._report_ignoring(function, child) # # Flesh out the SIP context for the rules engine. # sip["template_parameters"] = template_parameters if function.kind in [CursorKind.CONSTRUCTOR, CursorKind.DESTRUCTOR]: sip["fn_result"] = "" else: sip["fn_result"] = function.result_type.spelling sip["parameters"] = parameters sip["prefix"], sip["suffix"] = self._fn_get_decorators(function) modifying_rule = self.rules.function_rules().apply(container, function, sip) pad = " " * (level * 4) if sip["name"]: # # Any method-related code (%MethodCode, %VirtualCatcherCode, VirtualCallCode # or other method-related directives)? # self.rules.methodcode(function, sip) decl = "" if modifying_rule: decl += "// Modified {} (by {}):\n".format(SipGenerator.describe(function), modifying_rule) + pad decl += pad.join(parameter_modifying_rules) if parameter_modifying_rules: decl += pad decl += sip["name"] + "(" + ", ".join(sip["parameters"]) + ")" if sip["fn_result"]: decl = sip["fn_result"] + " " + decl decl = pad + sip["prefix"] + decl + sip["suffix"] if sip["template_parameters"]: decl = pad + "template <" + ", ".join(sip["template_parameters"]) + ">\n" + decl decl += ";\n" decl += sip["code"] else: decl = pad + "// Discarded {} (by {})\n".format(SipGenerator.describe(function), modifying_rule) return decl def _fn_get_decorators(self, function): """ The parser does not provide direct access to the complete keywords (explicit, const, static, etc) of a function in the displayname. It would be nice to get these from the AST, but I cannot find where they are hiding. Now, we could resort to using the original source. That does not bode well if you have macros (QOBJECT, xxxDEPRECATED?), inlined bodies and the like, using the rule engine could be used to patch corner cases... ...or we can try to guess what SIP cares about, i.e static and maybe const. Luckily (?), we have those to hand! :param function: The function object. :return: prefix, suffix String containing any prefix or suffix keywords. """ suffix = "" if function.is_const_method(): suffix += " const" prefix = "" if function.is_static_method(): prefix += "static " if function.is_virtual_method(): prefix += "virtual " if function.is_pure_virtual_method(): suffix += " = 0" return prefix, suffix def _fn_get_parameter_default(self, function, parameter): """ The parser does not seem to provide access to the complete text of a parameter. This makes it hard to find any default values, so we: 1. Run the lexer from "here" to the end of the file, bailing out when we see the "," or a ")" marking the end. 2. Watch for the assignment. """ def _get_param_type(parameter): result = parameter.type.get_declaration().type if result.kind != TypeKind.ENUM and result.kind != TypeKind.TYPEDEF and parameter.type.kind == TypeKind.LVALUEREFERENCE: if parameter.type.get_pointee().get_declaration().type.kind != TypeKind.INVALID: return parameter.type.get_pointee().get_declaration().type return parameter.type.get_pointee() if parameter.type.get_declaration().type.kind == TypeKind.INVALID: return parameter.type if (parameter.type.get_declaration().type.kind == TypeKind.TYPEDEF): isQFlags = False for member in parameter.type.get_declaration().get_children(): if member.kind == CursorKind.TEMPLATE_REF and member.spelling == "QFlags": isQFlags = True if isQFlags and member.kind == CursorKind.TYPE_REF: result = member.type break return result def _get_param_value(text, parameterType): if text == "0" or text == "nullptr": return text if text == "{}": if parameterType.kind == TypeKind.ENUM: return "0" if parameterType.kind == TypeKind.POINTER: return "nullptr" if parameterType.spelling.startswith("const "): return parameterType.spelling[6:] + "()" return parameterType.spelling + "()" if not "::" in parameterType.spelling: return text try: typeText, typeInit = text.split("(") typeInit = "(" + typeInit except: typeText = text typeInit = "" if parameterType.kind == TypeKind.ENUM and parameterType.get_declaration().is_scoped_enum(): prefix = parameterType.spelling else: prefix = parameterType.spelling.rsplit("::", 1)[0] if "::" in typeText: typeText = typeText.rsplit("::", 1)[1] return prefix + "::" + typeText + typeInit for member in parameter.get_children(): if member.kind.is_expression(): possible_extent = SourceRange.from_locations(parameter.extent.start, function.extent.end) text = "" bracket_level = 0 found_start = False found_end = False for token in self.tu.get_tokens(extent=possible_extent): if (token.spelling == "="): found_start = True continue if token.spelling == "," and bracket_level == 0: found_end = True break elif token.spelling == "(": bracket_level += 1 text += token.spelling elif token.spelling == ")": if bracket_level == 0: found_end = True break bracket_level -= 1 text += token.spelling if bracket_level == 0: found_end = True break elif found_start: text += token.spelling if not found_end and text: RuntimeError(_("No end found for {}::{}, '{}'").format(function.spelling, parameter.spelling, text)) parameterType = _get_param_type(parameter) return _get_param_value(text, parameterType) return "" def _typedef_get(self, container, typedef, level): """ Generate the translation for a typedef. :param container: A class or namespace. :param typedef: The typedef object. :param level: Recursion level controls indentation. :return: A string. """ sip = { "name": typedef.displayname, "decl": typedef.underlying_typedef_type.spelling, "annotations": set(), } self.rules.typedef_rules().apply(container, typedef, sip) pad = " " * (level * 4) if sip["name"]: decl = pad + "typedef {} {}".format(sip["decl"], sip["name"]) decl += ";\n" else: decl = pad + "// Discarded {}\n".format(SipGenerator.describe(typedef)) return decl def _var_get(self, container, variable, level): """ Generate the translation for a variable. :param container: A class or namespace. :param variable: The variable object. :param level: Recursion level controls indentation. :return: A string. """ sip = { "name": variable.spelling } for child in variable.get_children(): if child.kind in TEMPLATE_KINDS + [CursorKind.STRUCT_DECL, CursorKind.UNION_DECL]: # # Ignore: # # TEMPLATE_KINDS, CursorKind.STRUCT_DECL, CursorKind.UNION_DECL: : The variable type. # pass else: text = self._read_source(child.extent) if self.skippable_attribute(variable, child, text, sip): if not sip["name"]: return "" else: SipGenerator._report_ignoring(variable, child) # # Flesh out the SIP context for the rules engine. # decl = "{} {}".format(variable.type.spelling, variable.spelling) sip["decl"] = decl modifying_rule = self.rules.variable_rules().apply(container, variable, sip) pad = " " * (level * 4) if sip["name"]: decl = sip["decl"] # # SIP does not support protected variables, so we ignore them. # if variable.access_specifier == AccessSpecifier.PROTECTED: decl = pad + "// Discarded {}\n".format(SipGenerator.describe(variable)) else: decl = pad + decl + ";\n" else: decl = pad + "// Discarded {} (by {})\n".format(SipGenerator.describe(variable), modifying_rule) return decl def _read_source(self, extent): """ Read the given range from the unpre-processed source. :param extent: The range of text required. """ # Extent columns are specified in bytes extract = self.unpreprocessed_source[extent.start.line - 1:extent.end.line] if extent.start.line == extent.end.line: extract[0] = extract[0][extent.start.column - 1:extent.end.column - 1] else: extract[0] = extract[0][extent.start.column - 1:] extract[-1] = extract[-1][:extent.end.column - 1] # # Return a single line of text. # Replace all kinds of newline variants (DOS, UNIX, MAC style) by single spaces # return b''.join(extract).decode('utf-8').replace("\r\n", " ").replace("\n", " ").replace("\r", " ") @staticmethod def _report_ignoring(parent, child, text=None): if not text: text = child.displayname or child.spelling logger.debug(_("Ignoring {} {} child {}").format(parent.kind.name, parent.spelling, SipGenerator.describe(child, text))) def main(argv=None): """ Take a single C++ header file and generate the corresponding SIP file. Beyond simple generation of the SIP file from the corresponding C++ - header file, a set of rules can be used to customise the generated + header file, a set of rules can be used to customize the generated SIP file. Examples: sip_generator.py /usr/include/KF5/KItemModels/kselectionproxymodel.h """ if argv is None: argv = sys.argv parser = argparse.ArgumentParser(epilog=inspect.getdoc(main), formatter_class=HelpFormatter) parser.add_argument("-v", "--verbose", action="store_true", default=False, help=_("Enable verbose output")) parser.add_argument("--flags", help=_("Semicolon-separated C++ compile flags to use")) parser.add_argument("--include_filename", help=_("C++ header include to compile")) parser.add_argument("libclang", help=_("libclang library to use for parsing")) parser.add_argument("project_rules", help=_("Project rules")) parser.add_argument("source", help=_("C++ header to process")) parser.add_argument("output", help=_("output filename to write")) try: args = parser.parse_args(argv[1:]) if args.verbose: logging.basicConfig(level=logging.DEBUG, format='%(asctime)s %(name)s %(levelname)s: %(message)s') else: logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s') # # Generate! # cindex.Config.set_library_file(args.libclang) rules = rules_engine.rules(args.project_rules) g = SipGenerator(rules, args.flags.lstrip().split(";"), args.verbose) body, includes = g.create_sip(args.source, args.include_filename) with open(args.output, "w") as outputFile: outputFile.write(body) except Exception as e: tbk = traceback.format_exc() print(tbk) return -1 if __name__ == "__main__": if sys.argv[1] != "--self-check": sys.exit(main()) else: cindex.Config.set_library_file(sys.argv[2]) diff --git a/modules/ECMGenerateExportHeader.cmake b/modules/ECMGenerateExportHeader.cmake index 7de9aa6..52dd29d 100644 --- a/modules/ECMGenerateExportHeader.cmake +++ b/modules/ECMGenerateExportHeader.cmake @@ -1,758 +1,758 @@ #.rst: # ECMGenerateExportHeader # ----------------------- # # This module provides the ``ecm_generate_export_header`` function for # generating export macros for libraries with version-based control over # visibility of and compiler warnings for deprecated API for the library user, # as well as over excluding deprecated API and their implementation when # building the library itself. # # For preparing some values useful in the context it also provides a function # ``ecm_export_header_format_version``. # # :: # # ecm_generate_export_header( # VERSION # [BASE_NAME ] # [GROUP_BASE_NAME ] # [EXPORT_MACRO_NAME ] # [EXPORT_FILE_NAME ] # [DEPRECATED_MACRO_NAME ] # [NO_EXPORT_MACRO_NAME ] # [INCLUDE_GUARD_NAME ] # [STATIC_DEFINE ] # [PREFIX_NAME ] # [DEPRECATED_BASE_VERSION ] # [DEPRECATION_VERSIONS [ [...]]] # [EXCLUDE_DEPRECATED_BEFORE_AND_AT ] # [NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE] # [NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE] # [CUSTOM_CONTENT_FROM_VARIABLE ] # ) # # ``VERSION`` specifies the version of the library, given in the format # "..". # # ``GROUP_BASE_NAME`` specifies the name to use for the macros defining # library group default values. If set, this will generate code supporting # ``_NO_DEPRECATED_WARNINGS``, # ``_DISABLE_DEPRECATED_BEFORE_AND_AT``, # ``_DEPRECATED_WARNINGS_SINCE`` and # ``_NO_DEPRECATED`` (see below). # If not set, the generated code will ignore any such macros. # # ``DEPRECATED_BASE_VERSION`` specifies the default version before and at which # deprecated API is disabled. The default is the value of # "" if set, or ".0.0", with # taken from . # # ``DEPRECATION_VERSIONS`` specifies versions in "." format in # which API was declared deprecated. Any version used with the generated # macro ``_DEPRECATED_VERSION(major, minor, text)`` # needs to be listed here, otherwise the macro will fail to work. # # ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` specifies the version for which all API # deprecated before and at should be excluded from the build completely. # Possible values are "0" (default), "CURRENT" (which resolves to ) # and a version string in the format "..". # # ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` specifies that the definition # ``_DEPRECATED_WARNINGS_SINCE`` will # not be set for the library inside its own build, and thus will be defined # by either explicit definition in the build system configuration or by the # default value mechanism (see below). # The default is that it is set for the build, to the version specified by # ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so no deprecation warnings are # done for any own deprecated API used in the library implementation itself. # # ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` specifies that the definition # ``_DISABLE_DEPRECATED_BEFORE_AND_AT`` will # not be set in the public interface of the library inside its own build, and # the same for the definition # ``_DEPRECATED_WARNINGS_SINCE`` (if not # disabled by ``NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE`` already). # The default is that they are set, to the version specified by # ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``, so e.g. test and examples part of the # project automatically build against the full API included in the build and # without any deprecation warnings for it. # # # The function ``ecm_generate_export_header`` defines C++ preprocessor macros # in the generated export header, some for use in the sources of the library # the header is generated for, other for use by projects linking agsinst the # library. # # The macros for use in the library C++ sources are these, next to those also # defined by `GenerateExportHeader # `_: # # ``_DEPRECATED_VERSION(major, minor, text)`` # to use to conditionally set a # ``_DEPRECATED`` macro for a class, struct # or function (other elements to be supported in future versions), depending # on the visibility macro flags set (see below) # # ``_ENABLE_DEPRECATED_SINCE(major, minor)`` # evaluates to ``TRUE`` or ``FALSE`` depending on the visibility macro flags # set (see below). To be used mainly with ``#if``/``#endif`` to mark sections # of code which should be included depending on the visibility requested. # # ``_BUILD_DEPRECATED_SINCE(major, minor)`` # evaluates to ``TRUE`` or ``FALSE`` depending on the value of # ``EXCLUDE_DEPRECATED_BEFORE_AND_AT``. To be used mainly with # ``#if``/``#endif`` to mark sections of two types of code: implementation # code for deprecated API and declaration code of deprecated API which only # may be disabled at build time of the library for BC reasons (e.g. virtual # methods, see notes below). # # ``_EXCLUDE_DEPRECATED_BEFORE_AND_AT`` # holds the version used to exclude deprecated API at build time of the # library. # # The macros used to control visibility when building against the library are: # # ``_DISABLE_DEPRECATED_BEFORE_AND_AT`` # definition to set to a value in single hex number version notation # (``0x``). # # ``_NO_DEPRECATED`` # flag to define to disable all deprecated API, being a shortcut for # settings ``_DISABLE_DEPRECATED_BEFORE_AND_AT`` # to the current version. If both are set, this flag overrules. # # ``_DEPRECATED_WARNINGS_SINCE`` # definition to set to a value in single hex number version notation # (``0x``). Warnings will be only activated for # API deprecated up to and including the version. If # ``_DISABLE_DEPRECATED_BEFORE_AND_AT`` # is set (directly or via the group default), it will default to that # version, resulting in no warnings. Otherwise the default is the current # version, resulting in warnings for all deprecated API. # # ``_NO_DEPRECATED_WARNINGS`` # flag to define to disable all deprecation warnings, being a shortcut for # setting ``_DEPRECATED_WARNINGS_SINCE`` # to "0". If both are set, this flag overrules. # # When the ``GROUP_BASE_NAME`` has been used, the same macros but with the # given ```` prefix are available to define the defaults of -# these macros, if not explicitely set. +# these macros, if not explicitly set. # # Note: The tricks applied here for hiding deprecated API to the compiler # when building against a library do not work for all deprecated API: # # * virtual methods need to stay visible to the compiler to build proper # virtual method tables for subclasses # * enumerators from enums cannot be simply removed, as this changes # auto values of following enumerators, also can poke holes in enumerator # series used as index into tables # # In such cases the API can be only "hidden" at build time of the library, # itself, by generated hard coded macro settings, using # ``_BUILD_DEPRECATED_SINCE(major, minor)``. # # Examples: # # Preparing a library "Foo" created by target "foo", which is part of a group # of libraries "Bar", where some API of "Foo" got deprecated at versions # 5.0 & 5.12: # # .. code-block:: cmake # # ecm_generate_export_header(foo # GROUP_BASE_NAME BAR # VERSION ${FOO_VERSION} # DEPRECATION_VERSIONS 5.0 5.12 # ) # # In the library "Foo" sources in the headers the API would be prepared like # this, using the generated macros ``FOO_ENABLE_DEPRECATED_SINCE`` and # ``FOO_DEPRECATED_VERSION``: # # .. code-block:: cpp # # #include # # #if FOO_ENABLE_DEPRECATED_SINCE(5, 0) # /** # * @deprecated Since 5.0 # */ # FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()") # FOO_EXPORT void doFoo(); # #endif # # #if FOO_ENABLE_DEPRECATED_SINCE(5, 12) # /** # * @deprecated Since 5.12 # */ # FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()") # FOO_EXPORT void doBar(); # #endif # # Projects linking against the "Foo" library can control which part of its # deprecated API should be hidden to the compiler by adding a definition # using the ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` macro variable set to the # desired value (in version hex number notation): # # .. code-block:: cmake # # add_definitions(-DFOO_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000) # # Or using the macro variable of the group: # # .. code-block:: cmake # # add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050000) # # If both are specified, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` will take # precedence. # # To build a variant of a library with some deprecated API completely left # out from the build, not only optionally invisible to consumers, one uses the # ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` parameter. This is best combined with a # cached CMake variable. # # .. code-block:: cmake # # set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control the range of deprecated API excluded from the build [default=0].") # # ecm_generate_export_header(foo # VERSION ${FOO_VERSION} # EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT} # DEPRECATION_VERSIONS 5.0 5.12 # ) # # The macros used in the headers for library consumers are reused for # disabling the API excluded in the build of the library. For disabling the # implementation of that API as well as for disabling deprecated API which # only can be disabled at build time of the library for BC reasons, one # uses the generated macro ``FOO_BUILD_DEPRECATED_SINCE``, like this: # # .. code-block:: cpp # # #include # # enum Bars { # One, # #if FOO_BUILD_DEPRECATED_SINCE(5, 0) # Two, # #endif # Three, # }; # # #if FOO_ENABLE_DEPRECATED_SINCE(5, 0) # /** # * @deprecated Since 5.0 # */ # FOO_DEPRECATED_VERSION(5, 0, "Use doFoo2()") # FOO_EXPORT void doFoo(); # #endif # # #if FOO_ENABLE_DEPRECATED_SINCE(5, 12) # /** # * @deprecated Since 5.12 # */ # FOO_DEPRECATED_VERSION(5, 12, "Use doBar2()") # FOO_EXPORT void doBar(); # #endif # # class FOO_EXPORT Foo { # public: # #if FOO_BUILD_DEPRECATED_SINCE(5, 0) # /** # * @deprecated Since 5.0 # */ # FOO_DEPRECATED_VERSION(5, 0, "Feature removed") # virtual void doWhat(); # #endif # }; # # .. code-block:: cpp # # #if FOO_BUILD_DEPRECATED_SINCE(5, 0) # void doFoo() # { # // [...] # } # #endif # # #if FOO_BUILD_DEPRECATED_SINCE(5, 12) # void doBar() # { # // [...] # } # #endif # # #if FOO_BUILD_DEPRECATED_SINCE(5, 0) # void Foo::doWhat() # { # // [...] # } # #endif # # So e.g. if ``EXCLUDE_DEPRECATED_BEFORE_AND_AT`` is set to "5.0.0", the # enumerator ``Two`` as well as the methods ``::doFoo()`` and ``Foo::doWhat()`` # will be not available to library consumers. The methods will not have been # compiled into the library binary, and the declarations will be hidden to the # compiler, ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` also cannot be used to # reactivate them. # # When using the ``NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE`` and the project # for the "Foo" library includes also tests and examples linking against the # library and using deprecated API (like tests covering it), one better -# explicitely sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets +# explicitly sets ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT`` for those targets # to the version before and at which all deprecated API has been excluded from # the build. # Even more when building against other libraries from the same group "Bar" and # disabling some deprecated API of those libraries using the group macro # ``BAR_DISABLE_DEPRECATED_BEFORE_AND_AT``, which also works as default for # ``FOO_DISABLE_DEPRECATED_BEFORE_AND_AT``. # # To get the hex number style value the helper macro # ``ecm_export_header_format_version()`` will be used: # # .. code-block:: cmake # # set(EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 CACHE STRING "Control what part of deprecated API is excluded from build [default=0].") # # ecm_generate_export_header(foo # VERSION ${FOO_VERSION} # GROUP_BASE_NAME BAR # EXCLUDE_DEPRECATED_BEFORE_AND_AT ${EXCLUDE_DEPRECATED_BEFORE_AND_AT} # NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE # DEPRECATION_VERSIONS 5.0 5.12 # ) # # ecm_export_header_format_version(${EXCLUDE_DEPRECATED_BEFORE_AND_AT} # CURRENT_VERSION ${FOO_VERSION} # HEXNUMBER_VAR foo_no_deprecated_before_and_at # ) # # # disable all deprecated API up to 5.9.0 from all other libs of group "BAR" that we use ourselves # add_definitions(-DBAR_DISABLE_DEPRECATED_BEFORE_AND_AT=0x050900) # # add_executable(app app.cpp) # target_link_libraries(app foo) # target_compile_definitions(app # PRIVATE "FOO_DISABLE_DEPRECATED_BEFORE_AND_AT=${foo_no_deprecated_before_and_at}") # # Since 5.64.0. #============================================================================= # Copyright 2019 Friedrich W. H. Kossebau # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # # 1. Redistributions of source code must retain the copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # 3. The name of the author may not be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR # IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES # OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. # IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF # THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. include(GenerateExportHeader) include(CMakeParseArguments) # helper method function(_ecm_geh_generate_hex_number _var_name _version) set(_hexnumber 0) set(version_regex "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$") string(REGEX REPLACE ${version_regex} "\\1" _version_major "${_version}") string(REGEX REPLACE ${version_regex} "\\2" _version_minor "${_version}") string(REGEX REPLACE ${version_regex} "\\3" _version_patch "${_version}") set(_outputformat) if (NOT CMAKE_VERSION VERSION_LESS 3.13) set(_outputformat OUTPUT_FORMAT HEXADECIMAL) endif() math(EXPR _hexnumber "${_version_major}*65536 + ${_version_minor}*256 + ${_version_patch}" ${_outputformat}) set(${_var_name} ${_hexnumber} PARENT_SCOPE) endfunction() function(ecm_export_header_format_version _version) set(options ) set(oneValueArgs CURRENT_VERSION STRING_VAR HEXNUMBER_VAR ) set(multiValueArgs ) cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) if (NOT ARGS_STRING_VAR AND NOT ARGS_HEXNUMBER_VAR) message(FATAL_ERROR "No STRING_VAR or HEXNUMBER_VAR passed when calling ecm_export_header_format_version().") endif() if(_version STREQUAL "CURRENT") if (NOT ARGS_CURRENT_VERSION ) message(FATAL_ERROR "\"CURRENT\" as version value not supported when CURRENT_VERSION not passed on calling ecm_export_header_format_version().") endif() set(_version ${ARGS_CURRENT_VERSION}) endif() if (ARGS_STRING_VAR) set(${ARGS_STRING_VAR} ${_version} PARENT_SCOPE) endif() if (ARGS_HEXNUMBER_VAR) set(_hexnumber 0) # by default build all deprecated API if(_version) _ecm_geh_generate_hex_number(_hexnumber ${_version}) endif() set(${ARGS_HEXNUMBER_VAR} ${_hexnumber} PARENT_SCOPE) endif() endfunction() function(ecm_generate_export_header target) set(options NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE ) set(oneValueArgs BASE_NAME GROUP_BASE_NAME EXPORT_FILE_NAME DEPRECATED_BASE_VERSION VERSION EXCLUDE_DEPRECATED_BEFORE_AND_AT EXPORT_MACRO_NAME DEPRECATED_MACRO_NAME NO_EXPORT_MACRO_NAME INCLUDE_GUARD_NAME STATIC_DEFINE PREFIX_NAME CUSTOM_CONTENT_FROM_VARIABLE ) set(multiValueArgs DEPRECATION_VERSIONS ) cmake_parse_arguments(ARGS "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) # args sanity check if (NOT ARGS_VERSION) message(FATAL_ERROR "No VERSION passed when calling ecm_generate_export_header().") endif() if (ARGS_INCLUDE_GUARD_NAME AND CMAKE_VERSION VERSION_LESS 3.11) message(FATAL_ERROR "Argument INCLUDE_GUARD_NAME needs at least CMake 3.11 when calling ecm_generate_export_header().") endif() if (NOT ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT) set(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT 0) elseif(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT STREQUAL "CURRENT") set(ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT ${ARGS_VERSION}) endif() if (NOT DEFINED ARGS_DEPRECATED_BASE_VERSION) if (ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT) set(ARGS_DEPRECATED_BASE_VERSION "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}") else() string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)\\.([0-9]+)$" "\\1" _version_major "${ARGS_VERSION}") set(ARGS_DEPRECATED_BASE_VERSION "${_version_major}.0.0") endif() else() if(ARGS_DEPRECATED_BASE_VERSION STREQUAL "CURRENT") set(ARGS_DEPRECATED_BASE_VERSION ${ARGS_VERSION}) endif() if (ARGS_DEPRECATED_BASE_VERSION VERSION_LESS ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT) message(STATUS "DEPRECATED_BASE_VERSION (${ARGS_DEPRECATED_BASE_VERSION}) was lower than EXCLUDE_DEPRECATED_BEFORE_AND_AT (${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}) when calling ecm_generate_export_header(), raising to that.") set(ARGS_DEPRECATED_BASE_VERSION "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}") endif() endif() if(NOT ARGS_BASE_NAME) set(ARGS_BASE_NAME "${target}") endif() string(TOUPPER "${ARGS_BASE_NAME}" _upper_base_name) string(TOLOWER "${ARGS_BASE_NAME}" _lower_base_name) if(NOT ARGS_EXPORT_FILE_NAME) set(ARGS_EXPORT_FILE_NAME "${_lower_base_name}_export.h") endif() _ecm_geh_generate_hex_number(_version_hexnumber "${ARGS_VERSION}") if (ARGS_DEPRECATED_BASE_VERSION STREQUAL "0") set(_default_disabled_deprecated_version_hexnumber "0") else() _ecm_geh_generate_hex_number(_default_disabled_deprecated_version_hexnumber "${ARGS_DEPRECATED_BASE_VERSION}") endif() set(_macro_base_name "${ARGS_PREFIX_NAME}${_upper_base_name}") if (ARGS_EXPORT_MACRO_NAME) set(_export_macro_name "${ARGS_EXPORT_MACRO_NAME}") else() set(_export_macro_name "${_macro_base_name}_EXPORT") endif() if (ARGS_NO_EXPORT_MACRO_NAME) set(_no_export_macro_name "${ARGS_NO_EXPORT_MACRO_NAME}") else() set(_no_export_macro_name "${_macro_base_name}_NO_EXPORT") endif() if (ARGS_DEPRECATED_MACRO_NAME) set(_deprecated_macro_name "${ARGS_DEPRECATED_MACRO_NAME}") else() set(_deprecated_macro_name "${_macro_base_name}_DEPRECATED") endif() if(NOT IS_ABSOLUTE ${ARGS_EXPORT_FILE_NAME}) set(ARGS_EXPORT_FILE_NAME "${CMAKE_CURRENT_BINARY_DIR}/${ARGS_EXPORT_FILE_NAME}") endif() set_property(TARGET ${target} APPEND PROPERTY AUTOGEN_TARGET_DEPENDS "${ARGS_EXPORT_FILE_NAME}") # build with all the API not excluded, ensure all deprecated API is visible in the build itselt _ecm_geh_generate_hex_number(_hexnumber ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}) set(_disabling_visibility_definition "${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT=${_hexnumber}") target_compile_definitions(${target} PRIVATE "${_disabling_visibility_definition}") if (NOT ARGS_NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE) target_compile_definitions(${target} INTERFACE "$") endif() if(NOT ARGS_NO_BUILD_SET_DEPRECATED_WARNINGS_SINCE) set(_enabling_warnings_definition "${_macro_base_name}_DEPRECATED_WARNINGS_SINCE=${_hexnumber}") target_compile_definitions(${target} PRIVATE "${_enabling_warnings_definition}") if (NOT ARGS_NO_DEFINITION_EXPORT_TO_BUILD_INTERFACE) target_compile_definitions(${target} INTERFACE "$") endif() endif() # for the set of compiler versions supported by ECM/KF we can assume those attributes supported # KF6: with C++14 support expected, switch to always use [[deprecated(text)]] if (CMAKE_C_COMPILER_ID STREQUAL "GNU" OR CMAKE_C_COMPILER_ID MATCHES "Clang") set(_decl_deprecated_text_definition "__attribute__ ((__deprecated__(text)))") elseif(MSVC) set(_decl_deprecated_text_definition "__declspec(deprecated(text))") else() set(_decl_deprecated_text_definition "${_macro_base_name}_DECL_DEPRECATED") endif() # generate header file set(_output " #define ${_macro_base_name}_DECL_DEPRECATED_TEXT(text) ${_decl_deprecated_text_definition} #define ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, patch) ((major<<16)|(minor<<8)|(patch)) " ) if (ARGS_GROUP_BASE_NAME) string(TOUPPER "${ARGS_GROUP_BASE_NAME}" _upper_group_name) string(APPEND _output " /* Take any defaults from group settings */ #if !defined(${_macro_base_name}_NO_DEPRECATED) && !defined(${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) # ifdef ${_upper_group_name}_NO_DEPRECATED # define ${_macro_base_name}_NO_DEPRECATED # elif defined(${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) # define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT # endif #endif #if !defined(${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) && defined(${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) # define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_upper_group_name}_DISABLE_DEPRECATED_BEFORE_AND_AT #endif #if !defined(${_macro_base_name}_NO_DEPRECATED_WARNINGS) && !defined(${_macro_base_name}_DEPRECATED_WARNINGS_SINCE) # ifdef ${_upper_group_name}_NO_DEPRECATED_WARNINGS # define ${_macro_base_name}_NO_DEPRECATED_WARNINGS # elif defined(${_upper_group_name}_DEPRECATED_WARNINGS_SINCE) # define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_upper_group_name}_DEPRECATED_WARNINGS_SINCE # endif #endif #if !defined(${_macro_base_name}_DEPRECATED_WARNINGS_SINCE) && defined(${_upper_group_name}_DEPRECATED_WARNINGS_SINCE) # define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_upper_group_name}_DEPRECATED_WARNINGS_SINCE #endif " ) endif() string(APPEND _output " #if defined(${_macro_base_name}_NO_DEPRECATED) # undef ${_deprecated_macro_name} # define ${_deprecated_macro_name}_EXPORT ${_export_macro_name} # define ${_deprecated_macro_name}_NO_EXPORT ${_no_export_macro_name} #elif defined(${_macro_base_name}_NO_DEPRECATED_WARNINGS) # define ${_deprecated_macro_name} # define ${_deprecated_macro_name}_EXPORT ${_export_macro_name} # define ${_deprecated_macro_name}_NO_EXPORT ${_no_export_macro_name} #else # define ${_deprecated_macro_name} ${_macro_base_name}_DECL_DEPRECATED # define ${_deprecated_macro_name}_EXPORT ${_macro_base_name}_DECL_DEPRECATED_EXPORT # define ${_deprecated_macro_name}_NO_EXPORT ${_macro_base_name}_DECL_DEPRECATED_NO_EXPORT #endif " ) if (ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT) message(STATUS "Excluding from build all API deprecated before and at: ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}") # TODO: the generated code ideally would emit a warning if some consumer used a value # smaller then what the the build was done with _ecm_geh_generate_hex_number(_excluded_before_and_at_version_hexnumber "${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT}") string(APPEND _output " /* Build was done with the API removed deprecated before: ${ARGS_EXCLUDE_DEPRECATED_BEFORE_AND_AT} */ #define ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT ${_excluded_before_and_at_version_hexnumber} #ifdef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT # if ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT < ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT # undef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT # define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT # endif #endif #define ${_macro_base_name}_BUILD_DEPRECATED_SINCE(major, minor) (ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, 0) > ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT) " ) else() string(APPEND _output " /* No deprecated API had been removed from build */ #define ${_macro_base_name}_EXCLUDE_DEPRECATED_BEFORE_AND_AT 0 #define ${_macro_base_name}_BUILD_DEPRECATED_SINCE(major, minor) 1 " ) endif() string(APPEND _output " #ifdef ${_macro_base_name}_NO_DEPRECATED # define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_version_hexnumber} #endif #ifdef ${_macro_base_name}_NO_DEPRECATED_WARNINGS # define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE 0 #endif #ifndef ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE # ifdef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT # define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT # else # define ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE ${_version_hexnumber} # endif #endif #ifndef ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT # define ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT ${_default_disabled_deprecated_version_hexnumber} #endif #ifdef ${_deprecated_macro_name} # define ${_macro_base_name}_ENABLE_DEPRECATED_SINCE(major, minor) (ECM_GENERATEEXPORTHEADER_VERSION_VALUE(major, minor, 0) > ${_macro_base_name}_DISABLE_DEPRECATED_BEFORE_AND_AT) #else # define ${_macro_base_name}_ENABLE_DEPRECATED_SINCE(major, minor) 0 #endif " ) if (DEFINED ARGS_DEPRECATION_VERSIONS) set(_major_versions) foreach(_version ${ARGS_DEPRECATION_VERSIONS}) _ecm_geh_generate_hex_number(_version_hexnumber "${_version}.0") string(REPLACE "." "_" _underscored_version "${_version}") string(REGEX REPLACE "^([0-9]+)\\.([0-9]+)$" "\\1" _version_major "${_version}") # IN_LIST only since cmake 3.3 set(_in_list FALSE) foreach(_v ${_major_versions}) if (_v STREQUAL _version_major) set(_in_list TRUE) break() endif() endforeach() if(NOT _in_list) list(APPEND _major_versions ${_version_major}) endif() string(APPEND _output " #if ${_macro_base_name}_DEPRECATED_WARNINGS_SINCE >= ${_version_hexnumber} # define ${_macro_base_name}_DEPRECATED_VERSION_${_underscored_version}(text) ${_macro_base_name}_DECL_DEPRECATED_TEXT(text) #else # define ${_macro_base_name}_DEPRECATED_VERSION_${_underscored_version}(text) #endif " ) endforeach() foreach(_major_version ${_major_versions}) string(APPEND _output "#define ${_macro_base_name}_DEPRECATED_VERSION_${_major_version}(minor, text) ${_macro_base_name}_DEPRECATED_VERSION_${_major_version}_##minor(text) " ) endforeach() string(APPEND _output "#define ${_macro_base_name}_DEPRECATED_VERSION(major, minor, text) ${_macro_base_name}_DEPRECATED_VERSION_##major(minor, \"Since \"#major\".\"#minor\". \" text) " ) endif() if (ARGS_CUSTOM_CONTENT_FROM_VARIABLE) string(APPEND _output "${ARGS_CUSTOM_CONTENT_FROM_VARIABLE}\n") endif() set(_header_file "${ARGS_EXPORT_FILE_NAME}") set(_header_work_file "${_header_file}.work") # prepare optional arguments to pass through to generate_export_header set(_include_guard_name_args) if (ARGS_INCLUDE_GUARD_NAME) set(_include_guard_name_args INCLUDE_GUARD_NAME "${ARGS_INCLUDE_GUARD_NAME}") endif() set(_export_macro_name_args) if (ARGS_EXPORT_MACRO_NAME) set(_export_macro_name_args EXPORT_MACRO_NAME "${ARGS_EXPORT_MACRO_NAME}") endif() set(_no_export_macro_name_args) if (ARGS_NO_EXPORT_MACRO_NAME) set(_no_export_macro_name_args ARGS_NO_EXPORT_MACRO_NAME "${ARGS_NO_EXPORT_MACRO_NAME}") endif() set(_prefix_name_args) if (ARGS_PREFIX_NAME) set(_prefix_name_args PREFIX_NAME "${ARGS_PREFIX_NAME}") endif() set(_static_define_args) if (ARGS_STATIC_DEFINE) set(_static_define_args STATIC_DEFINE "${ARGS_STATIC_DEFINE}") endif() # for older cmake verions we have to manually append our generated content # for newer we use CUSTOM_CONTENT_FROM_VARIABLE set(_custom_content_args) if (NOT CMAKE_VERSION VERSION_LESS 3.7) set(_custom_content_args CUSTOM_CONTENT_FROM_VARIABLE _output) endif() generate_export_header(${target} BASE_NAME ${ARGS_BASE_NAME} DEPRECATED_MACRO_NAME "${_macro_base_name}_DECL_DEPRECATED" ${_prefix_name_args} ${_export_macro_name_args} ${_no_export_macro_name_args} ${_static_define_args} EXPORT_FILE_NAME "${_header_work_file}" ${_include_guard_name_args} ${_custom_content_args} ) if (CMAKE_VERSION VERSION_LESS 3.7) if (ARGS_INCLUDE_GUARD_NAME) set(_include_guard "ECM_GENERATEEXPORTHEADER_${ARGS_INCLUDE_GUARD_NAME}") else() set(_include_guard "ECM_GENERATEEXPORTHEADER_${_upper_base_name}_EXPORT_H") endif() file(APPEND ${_header_work_file} " #ifndef ${_include_guard} #define ${_include_guard} ${_output} #endif /* ${_include_guard} */ " ) endif() # avoid rebuilding if there was no change execute_process( COMMAND ${CMAKE_COMMAND} -E copy_if_different "${_header_work_file}" "${_header_file}" ) file(REMOVE "${_header_work_file}") endfunction() diff --git a/tests/ECMGenerateExportHeaderTest/CMakeLists.txt b/tests/ECMGenerateExportHeaderTest/CMakeLists.txt index 5b25a7d..45ad611 100644 --- a/tests/ECMGenerateExportHeaderTest/CMakeLists.txt +++ b/tests/ECMGenerateExportHeaderTest/CMakeLists.txt @@ -1,120 +1,120 @@ set(installation_path "${CMAKE_CURRENT_BINARY_DIR}/installation/") macro(add_generate_export_header_library_test _exclude_deprecated_before_and_at) if("${ARGV1}" STREQUAL "WITH_GROUP") set(_set_group_option "-DSET_GROUP=TRUE") set(_library_buildname "library-${_exclude_deprecated_before_and_at}-group") else() set(_library_buildname "library-${_exclude_deprecated_before_and_at}") endif() add_test(NAME ecm_generate_export_header-build-${_library_buildname} COMMAND ${CMAKE_CTEST_COMMAND} --build-and-test "${CMAKE_CURRENT_SOURCE_DIR}/library" "${CMAKE_CURRENT_BINARY_DIR}/${_library_buildname}" --build-two-config --build-generator "${CMAKE_GENERATOR}" --build-makeprogram ${CMAKE_MAKE_PROGRAM} --build-project library --build-target install --build-options "-DEXCLUDE_DEPRECATED_BEFORE_AND_AT=${_exclude_deprecated_before_and_at}" "-DCMAKE_INSTALL_PREFIX:PATH=${installation_path}/${_library_buildname}" ${_set_group_option} --test-command dummy ) endmacro() macro(add_generate_export_header_consumer_test _test_variant _exclude_deprecated_before_and_at _group_test_mode _consumer_build) set(_extra_build_options ${ARGN}) if(_group_test_mode STREQUAL "GROUPLESS") set(_library "library-${_exclude_deprecated_before_and_at}") else() set(_library "library-${_exclude_deprecated_before_and_at}-group") endif() add_test(NAME ecm_generate_export_header-${_consumer_build} COMMAND ${CMAKE_CTEST_COMMAND} --build-and-test "${CMAKE_CURRENT_SOURCE_DIR}/consumer" "${CMAKE_CURRENT_BINARY_DIR}/${_consumer_build}" --build-two-config --build-generator "${CMAKE_GENERATOR}" --build-makeprogram ${CMAKE_MAKE_PROGRAM} --build-project consumer --build-options "-DTEST_VARIANT:STRING=${_test_variant}" "-DDEPRECATED_EXCLUDED_BEFORE_AND_AT:STRING=${_exclude_deprecated_before_and_at}" "-DLIBRARY:STRING=${_library}" "-DGROUP_MODE:STRING=${_group_test_mode}" ${_extra_build_options} --test-command dummy ) endmacro() macro(add_generate_export_header_consumer_disable_deprecated_before_and_at_test _disable_deprecated_before_and_at _exclude_deprecated_before_and_at _group_test_mode ) set(_consumer_build "consumer-${_disable_deprecated_before_and_at}-${_exclude_deprecated_before_and_at}-${_group_test_mode}") set(_extra_build_options "-DLIBRARY_DISABLE_DEPRECATED_BEFORE_AND_AT:STRING=${_disable_deprecated_before_and_at}" ) add_generate_export_header_consumer_test(DISABLE_DEPRECATED_BEFORE_AND_AT ${_exclude_deprecated_before_and_at} ${_group_test_mode} ${_consumer_build} ${_extra_build_options} ) endmacro() macro(add_generate_export_header_consumer_no_deprecated_test _exclude_deprecated_before_and_at _group_test_mode) set(_consumer_build "consumer-NO-DEPRECATED-${_exclude_deprecated_before_and_at}-${_group_test_mode}") add_generate_export_header_consumer_test(NO_DEPRECATED ${_exclude_deprecated_before_and_at} ${_group_test_mode} ${_consumer_build} ) endmacro() # prepare list of versions set(library_versions 0 2.0.0 CURRENT) list(LENGTH library_versions library_versions_count) math(EXPR _last_index ${library_versions_count}-1) # test generating the library with different EXCLUDE_DEPRECATED_BEFORE_AND_AT values # als install the generated libraries together incl. exported cmake targets, for use in tests below # TODO: wariant with DEPRECATED_BASE_VERSION foreach(_group_arg "" "WITH_GROUP") foreach(_index RANGE ${_last_index}) list(GET library_versions ${_index} _exclude_deprecated_before_and_at) add_generate_export_header_library_test(${_exclude_deprecated_before_and_at} ${_group_arg}) endforeach() endforeach() set(group_test_modes "GROUPLESS" "GROUP_USE_DIRECT" "GROUP_USE_GROUP") # test using the library, built with different EXCLUDE_DEPRECATED_BEFORE_AND_AT values, # while using different DISABLE_DEPRECATED_BEFORE_AND_AT values # TODO: test DEPRECATED_WARNINGS_SINCE foreach(_group_test_mode ${group_test_modes}) foreach(_exclude_index RANGE ${_last_index}) list(GET library_versions ${_exclude_index} _exclude_deprecated_before_and_at) # using disabled API limit below the excluded API limit is not supported and - # catched by the code generated from the ecm_generate_export_header, + # caught by the code generated from the ecm_generate_export_header, # so testing those combination will not work, so start from the excluded API limit foreach(_disable_index RANGE ${_exclude_index} ${_last_index}) list(GET library_versions ${_disable_index} _disable_deprecated_before_and_at) add_generate_export_header_consumer_disable_deprecated_before_and_at_test(${_disable_deprecated_before_and_at} ${_exclude_deprecated_before_and_at} ${_group_test_mode}) endforeach() endforeach() endforeach() # test with NO_DEPRECATED foreach(_group_test_mode ${group_test_modes}) foreach(_exclude_index RANGE ${_last_index}) list(GET library_versions ${_exclude_index} _exclude_deprecated_before_and_at) add_generate_export_header_consumer_no_deprecated_test(${_exclude_deprecated_before_and_at} ${_group_test_mode}) endforeach() endforeach()