src/third_party/WebKit/Source/bindings/scripts/compute_interfaces_info.py

   1 #!/usr/bin/python
   2 #
   3 # Copyright (C) 2013 Google Inc. All rights reserved.
   4 #
   5 # Redistribution and use in source and binary forms, with or without
   6 # modification, are permitted provided that the following conditions are
   7 # met:
   8 #
   9 #     * Redistributions of source code must retain the above copyright
  10 # notice, this list of conditions and the following disclaimer.
  11 #     * Redistributions in binary form must reproduce the above
  12 # copyright notice, this list of conditions and the following disclaimer
  13 # in the documentation and/or other materials provided with the
  14 # distribution.
  15 #     * Neither the name of Google Inc. nor the names of its
  16 # contributors may be used to endorse or promote products derived from
  17 # this software without specific prior written permission.
  18 #
  19 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 """Compute global interface information, including public information, dependencies, and inheritance.
  32
  33 Computed data is stored in a global variable, |interfaces_info|, and written as
  34 output (concretely, exported as a pickle). This is then used by the IDL compiler
  35 itself, so it does not need to compute global information itself, and so that
  36 inter-IDL dependencies are clear, since they are all computed here.
  37
  38 The |interfaces_info| pickle is a *global* dependency: any changes cause a full
  39 rebuild. This is to avoid having to compute which public data is visible by
  40 which IDL files on a file-by-file basis, which is very complex for little
  41 benefit.
  42 |interfaces_info| should thus only contain data about an interface that
  43 contains paths or is needed by *other* interfaces, e.g., path data (to abstract
  44 the compiler from OS-specific file paths) or public data (to avoid having to
  45 read other interfaces unnecessarily).
  46 It should *not* contain full information about an interface (e.g., all
  47 extended attributes), as this would cause unnecessary rebuilds.
  48
  49 |interfaces_info| is a dict, keyed by |interface_name|.
  50
  51 Current keys are:
  52 * dependencies:
  53     'implements_interfaces': targets of 'implements' statements
  54     'referenced_interfaces': reference interfaces that are introspected
  55                              (currently just targets of [PutForwards])
  56
  57 * inheritance:
  58     'ancestors': all ancestor interfaces
  59     'inherited_extended_attributes': inherited extended attributes
  60                                      (all controlling memory management)
  61
  62 * public:
  63     'is_callback_interface': bool, callback interface or not
  64     'implemented_as': value of [ImplementedAs=...] on interface (C++ class name)
  65
  66 * paths:
  67     'full_path': path to the IDL file, so can lookup an IDL by interface name
  68     'include_path': path for use in C++ #include directives
  69     'dependencies_full_paths': paths to dependencies (for merging into main)
  70     'dependencies_include_paths': paths for use in C++ #include directives
  71
  72 Note that all of these are stable information, unlikely to change without
  73 moving or deleting files (hence requiring a full rebuild anyway) or significant
  74 code changes (for inherited extended attributes).
  75
  76 Design doc: http://www.chromium.org/developers/design-documents/idl-build
  77 """
  78
  79 from collections import defaultdict
  80 import optparse
  81 import os
  82 import posixpath
  83 import sys
  84
  85 from utilities import get_file_contents, write_pickle_file, get_interface_extended_attributes_from_idl, is_callback_interface_from_idl, get_partial_interface_name_from_idl, get_implements_from_idl, get_parent_interface, get_put_forward_interfaces_from_idl
  86
  87 module_path = os.path.dirname(__file__)
  88 source_path = os.path.normpath(os.path.join(module_path, os.pardir, os.pardir))
  89
  90 INHERITED_EXTENDED_ATTRIBUTES = set([
  91     'ActiveDOMObject',
  92     'DependentLifetime',
  93     'GarbageCollected',
  94     'WillBeGarbageCollected',
  95 ])
  96
  97 # Main variable (filled in and exported)
  98 interfaces_info = {}
  99
 100 # Auxiliary variables (not visible to future build steps)
 101 partial_interface_files = defaultdict(lambda: {
 102     'full_paths': [],
 103     'include_paths': [],
 104 })
 105 parent_interfaces = {}
 106 inherited_extended_attributes_by_interface = {}  # interface name -> extended attributes
 107
 108
 109 class IdlInterfaceFileNotFoundError(Exception):
 110     """Raised if the IDL file implementing an interface cannot be found."""
 111     pass
 112
 113
 114 def parse_options():
 115     usage = 'Usage: %prog [options] [generated1.idl]...'
 116     parser = optparse.OptionParser(usage=usage)
 117     parser.add_option('--idl-files-list', help='file listing IDL files')
 118     parser.add_option('--interfaces-info-file', help='output pickle file')
 119     parser.add_option('--write-file-only-if-changed', type='int', help='if true, do not write an output file if it would be identical to the existing one, which avoids unnecessary rebuilds in ninja')
 120
 121     options, args = parser.parse_args()
 122     if options.interfaces_info_file is None:
 123         parser.error('Must specify an output file using --interfaces-info-file.')
 124     if options.idl_files_list is None:
 125         parser.error('Must specify a file listing IDL files using --idl-files-list.')
 126     if options.write_file_only_if_changed is None:
 127         parser.error('Must specify whether file is only written if changed using --write-file-only-if-changed.')
 128     options.write_file_only_if_changed = bool(options.write_file_only_if_changed)
 129     return options, args
 130
 131
 132 ################################################################################
 133 # Computations
 134 ################################################################################
 135
 136 def include_path(idl_filename, implemented_as=None):
 137     """Returns relative path to header file in POSIX format; used in includes.
 138
 139     POSIX format is used for consistency of output, so reference tests are
 140     platform-independent.
 141     """
 142     relative_path_local = os.path.relpath(idl_filename, source_path)
 143     relative_dir_local = os.path.dirname(relative_path_local)
 144     relative_dir_posix = relative_dir_local.replace(os.path.sep, posixpath.sep)
 145
 146     idl_file_basename, _ = os.path.splitext(os.path.basename(idl_filename))
 147     cpp_class_name = implemented_as or idl_file_basename
 148
 149     return posixpath.join(relative_dir_posix, cpp_class_name + '.h')
 150
 151
 152 def add_paths_to_partials_dict(partial_interface_name, full_path, this_include_path=None):
 153     paths_dict = partial_interface_files[partial_interface_name]
 154     paths_dict['full_paths'].append(full_path)
 155     if this_include_path:
 156         paths_dict['include_paths'].append(this_include_path)
 157
 158
 159 def compute_individual_info(idl_filename):
 160     full_path = os.path.realpath(idl_filename)
 161     idl_file_contents = get_file_contents(full_path)
 162
 163     extended_attributes = get_interface_extended_attributes_from_idl(idl_file_contents)
 164     implemented_as = extended_attributes.get('ImplementedAs')
 165     this_include_path = include_path(idl_filename, implemented_as)
 166
 167     # Handle partial interfaces
 168     partial_interface_name = get_partial_interface_name_from_idl(idl_file_contents)
 169     if partial_interface_name:
 170         add_paths_to_partials_dict(partial_interface_name, full_path, this_include_path)
 171         return
 172
 173     # If not a partial interface, the basename is the interface name
 174     interface_name, _ = os.path.splitext(os.path.basename(idl_filename))
 175
 176     # 'implements' statements can be included in either the file for the
 177     # implement*ing* interface (lhs of 'implements') or implement*ed* interface
 178     # (rhs of 'implements'). Store both for now, then merge to implement*ing*
 179     # interface later.
 180     left_interfaces, right_interfaces = get_implements_from_idl(idl_file_contents, interface_name)
 181
 182     interfaces_info[interface_name] = {
 183         'full_path': full_path,
 184         'implemented_as': implemented_as,
 185         'implemented_by_interfaces': left_interfaces,  # private, merged to next
 186         'implements_interfaces': right_interfaces,
 187         'include_path': this_include_path,
 188         # FIXME: temporary private field, while removing old treatement of
 189         # 'implements': http://crbug.com/360435
 190         'is_legacy_treat_as_partial_interface': 'LegacyTreatAsPartialInterface' in extended_attributes,
 191         'is_callback_interface': is_callback_interface_from_idl(idl_file_contents),
 192         # Interfaces that are referenced (used as types) and that we introspect
 193         # during code generation (beyond interface-level data ([ImplementedAs],
 194         # is_callback_interface, ancestors, and inherited extended attributes):
 195         # deep dependencies.
 196         # These cause rebuilds of referrers, due to the dependency, so these
 197         # should be minimized; currently only targets of [PutForwards].
 198         'referenced_interfaces': get_put_forward_interfaces_from_idl(idl_file_contents),
 199     }
 200
 201     # Record inheritance information
 202     inherited_extended_attributes_by_interface[interface_name] = dict(
 203             (key, value)
 204             for key, value in extended_attributes.iteritems()
 205             if key in INHERITED_EXTENDED_ATTRIBUTES)
 206     parent = get_parent_interface(idl_file_contents)
 207     if parent:
 208         parent_interfaces[interface_name] = parent
 209
 210
 211 def compute_inheritance_info(interface_name):
 212     """Compute inheritance information, namely ancestors and inherited extended attributes."""
 213     def generate_ancestors(interface_name):
 214         while interface_name in parent_interfaces:
 215             interface_name = parent_interfaces[interface_name]
 216             yield interface_name
 217
 218     ancestors = list(generate_ancestors(interface_name))
 219     inherited_extended_attributes = inherited_extended_attributes_by_interface[interface_name]
 220     for ancestor in ancestors:
 221         # Ancestors may not be present, notably if an ancestor is a generated
 222         # IDL file and we are running this script from run-bindings-tests,
 223         # where we don't generate these files.
 224         ancestor_extended_attributes = inherited_extended_attributes_by_interface.get(ancestor, {})
 225         inherited_extended_attributes.update(ancestor_extended_attributes)
 226
 227     interfaces_info[interface_name].update({
 228         'ancestors': ancestors,
 229         'inherited_extended_attributes': inherited_extended_attributes,
 230     })
 231
 232
 233 def compute_interfaces_info(idl_files):
 234     """Compute information about IDL files.
 235
 236     Information is stored in global interfaces_info.
 237     """
 238     # Compute information for individual files
 239     for idl_filename in idl_files:
 240         compute_individual_info(idl_filename)
 241
 242     # Once all individual files handled, can compute inheritance information
 243     # and dependencies
 244
 245     # Compute inheritance info
 246     for interface_name in interfaces_info:
 247         compute_inheritance_info(interface_name)
 248
 249     # Compute dependencies
 250     # Move implements info from implement*ed* interface (rhs of 'implements')
 251     # to implement*ing* interface (lhs of 'implements').
 252     # Note that moving an 'implements' statement between implementing and
 253     # implemented files does not change the info (or hence cause a rebuild)!
 254     for right_interface_name, interface_info in interfaces_info.iteritems():
 255         for left_interface_name in interface_info['implemented_by_interfaces']:
 256             interfaces_info[left_interface_name]['implements_interfaces'].append(right_interface_name)
 257         del interface_info['implemented_by_interfaces']
 258
 259     # An IDL file's dependencies are partial interface files that extend it,
 260     # and files for other interfaces that this interfaces implements.
 261     for interface_name, interface_info in interfaces_info.iteritems():
 262         partial_interface_paths = partial_interface_files[interface_name]
 263         partial_interfaces_full_paths = partial_interface_paths['full_paths']
 264         # Partial interface definitions each need an include, as they are
 265         # implemented in separate classes from the main interface.
 266         partial_interfaces_include_paths = partial_interface_paths['include_paths']
 267
 268         implemented_interfaces = interface_info['implements_interfaces']
 269         try:
 270             implemented_interfaces_info = [
 271                 interfaces_info[interface]
 272                 for interface in implemented_interfaces]
 273         except KeyError as key_name:
 274             raise IdlInterfaceFileNotFoundError('Could not find the IDL file where the following implemented interface is defined: %s' % key_name)
 275         implemented_interfaces_full_paths = [
 276             implemented_interface_info['full_path']
 277             for implemented_interface_info in implemented_interfaces_info]
 278         # Implemented interfaces don't need includes, as this is handled in
 279         # the Blink implementation (they are implemented on |impl| itself,
 280         # hence header is included in implementing class).
 281         # However, they are needed for legacy implemented interfaces that
 282         # are being treated as partial interfaces, until we remove these.
 283         # http://crbug.com/360435
 284         implemented_interfaces_include_paths = [
 285             implemented_interface_info['include_path']
 286             for implemented_interface_info in implemented_interfaces_info
 287             if implemented_interface_info['is_legacy_treat_as_partial_interface']]
 288
 289         interface_info.update({
 290             'dependencies_full_paths': (partial_interfaces_full_paths +
 291                                         implemented_interfaces_full_paths),
 292             'dependencies_include_paths': (partial_interfaces_include_paths +
 293                                            implemented_interfaces_include_paths),
 294         })
 295
 296     # Clean up temporary private information
 297     for interface_info in interfaces_info.itervalues():
 298         del interface_info['is_legacy_treat_as_partial_interface']
 299
 300
 301 ################################################################################
 302
 303 def main():
 304     options, args = parse_options()
 305
 306     # Static IDL files are passed in a file (generated at GYP time), due to OS
 307     # command line length limits
 308     with open(options.idl_files_list) as idl_files_list:
 309         idl_files = [line.rstrip('\n') for line in idl_files_list]
 310     # Generated IDL files are passed at the command line, since these are in the
 311     # build directory, which is determined at build time, not GYP time, so these
 312     # cannot be included in the file listing static files
 313     idl_files.extend(args)
 314
 315     compute_interfaces_info(idl_files)
 316     write_pickle_file(options.interfaces_info_file,
 317                       interfaces_info,
 318                       options.write_file_only_if_changed)
 319
 320
 321 if __name__ == '__main__':
 322     sys.exit(main())