third_party/WebKit/Source/bindings/scripts/code_generator_v8.py

   1 # Copyright (C) 2013 Google Inc. All rights reserved.
   2 #
   3 # Redistribution and use in source and binary forms, with or without
   4 # modification, are permitted provided that the following conditions are
   5 # met:
   6 #
   7 #     * Redistributions of source code must retain the above copyright
   8 # notice, this list of conditions and the following disclaimer.
   9 #     * Redistributions in binary form must reproduce the above
  10 # copyright notice, this list of conditions and the following disclaimer
  11 # in the documentation and/or other materials provided with the
  12 # distribution.
  13 #     * Neither the name of Google Inc. nor the names of its
  14 # contributors may be used to endorse or promote products derived from
  15 # this software without specific prior written permission.
  16 #
  17 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 """Generate Blink V8 bindings (.h and .cpp files).
  30
  31 If run itself, caches Jinja templates (and creates dummy file for build,
  32 since cache filenames are unpredictable and opaque).
  33
  34 This module is *not* concurrency-safe without care: bytecode caching creates
  35 a race condition on cache *write* (crashes if one process tries to read a
  36 partially-written cache). However, if you pre-cache the templates (by running
  37 the module itself), then you can parallelize compiling individual files, since
  38 cache *reading* is safe.
  39
  40 Input: An object of class IdlDefinitions, containing an IDL interface X
  41 Output: V8X.h and V8X.cpp
  42
  43 Design doc: http://www.chromium.org/developers/design-documents/idl-compiler
  44 """
  45
  46 import os
  47 import posixpath
  48 import re
  49 import sys
  50
  51 # Path handling for libraries and templates
  52 # Paths have to be normalized because Jinja uses the exact template path to
  53 # determine the hash used in the cache filename, and we need a pre-caching step
  54 # to be concurrency-safe. Use absolute path because __file__ is absolute if
  55 # module is imported, and relative if executed directly.
  56 # If paths differ between pre-caching and individual file compilation, the cache
  57 # is regenerated, which causes a race condition and breaks concurrent build,
  58 # since some compile processes will try to read the partially written cache.
  59 module_path, module_filename = os.path.split(os.path.realpath(__file__))
  60 third_party_dir = os.path.normpath(os.path.join(
  61     module_path, os.pardir, os.pardir, os.pardir, os.pardir))
  62 templates_dir = os.path.normpath(os.path.join(
  63     module_path, os.pardir, 'templates'))
  64 # Make sure extension is .py, not .pyc or .pyo, so doesn't depend on caching
  65 module_pyname = os.path.splitext(module_filename)[0] + '.py'
  66
  67 # jinja2 is in chromium's third_party directory.
  68 # Insert at 1 so at front to override system libraries, and
  69 # after path[0] == invoking script dir
  70 sys.path.insert(1, third_party_dir)
  71 import jinja2
  72
  73 from idl_definitions import Visitor
  74 import idl_types
  75 from idl_types import IdlType
  76 import v8_callback_interface
  77 import v8_dictionary
  78 from v8_globals import includes, interfaces
  79 import v8_interface
  80 import v8_types
  81 import v8_union
  82 from v8_utilities import capitalize, cpp_name, conditional_string, v8_class_name
  83 from utilities import KNOWN_COMPONENTS, idl_filename_to_component, is_valid_component_dependency, is_testing_target
  84
  85
  86 def render_template(include_paths, header_template, cpp_template,
  87                     template_context, component=None):
  88     template_context['code_generator'] = module_pyname
  89
  90     # Add includes for any dependencies
  91     template_context['header_includes'] = sorted(
  92         template_context['header_includes'])
  93
  94     for include_path in include_paths:
  95         if component:
  96             dependency = idl_filename_to_component(include_path)
  97             assert is_valid_component_dependency(component, dependency)
  98         includes.add(include_path)
  99
 100     template_context['cpp_includes'] = sorted(includes)
 101
 102     header_text = header_template.render(template_context)
 103     cpp_text = cpp_template.render(template_context)
 104     return header_text, cpp_text
 105
 106
 107 def set_global_type_info(info_provider):
 108     interfaces_info = info_provider.interfaces_info
 109     idl_types.set_ancestors(interfaces_info['ancestors'])
 110     IdlType.set_callback_interfaces(interfaces_info['callback_interfaces'])
 111     IdlType.set_dictionaries(interfaces_info['dictionaries'])
 112     IdlType.set_enums(info_provider.enumerations)
 113     IdlType.set_implemented_as_interfaces(interfaces_info['implemented_as_interfaces'])
 114     IdlType.set_garbage_collected_types(interfaces_info['garbage_collected_interfaces'])
 115     IdlType.set_will_be_garbage_collected_types(interfaces_info['will_be_garbage_collected_interfaces'])
 116     v8_types.set_component_dirs(interfaces_info['component_dirs'])
 117
 118
 119 def should_generate_code(definitions):
 120     return definitions.interfaces or definitions.dictionaries
 121
 122
 123 def depends_on_union_types(idl_type):
 124     """Returns true when a given idl_type depends on union containers
 125     directly.
 126     """
 127     if idl_type.is_union_type:
 128         return True
 129     if idl_type.is_array_or_sequence_type:
 130         return idl_type.element_type.is_union_type
 131     return False
 132
 133
 134 class TypedefResolver(Visitor):
 135     def __init__(self, info_provider):
 136         self.info_provider = info_provider
 137
 138     def resolve(self, definitions, definition_name):
 139         """Traverse definitions and resolves typedefs with the actual types."""
 140         self.typedefs = {}
 141         for name, typedef in self.info_provider.typedefs.iteritems():
 142             self.typedefs[name] = typedef.idl_type
 143         self.additional_includes = set()
 144         definitions.accept(self)
 145         self._update_dependencies_include_paths(definition_name)
 146
 147     def _update_dependencies_include_paths(self, definition_name):
 148         interface_info = self.info_provider.interfaces_info[definition_name]
 149         dependencies_include_paths = interface_info['dependencies_include_paths']
 150         for include_path in self.additional_includes:
 151             if include_path not in dependencies_include_paths:
 152                 dependencies_include_paths.append(include_path)
 153
 154     def _resolve_typedefs(self, typed_object):
 155         """Resolve typedefs to actual types in the object."""
 156         for attribute_name in typed_object.idl_type_attributes:
 157             try:
 158                 idl_type = getattr(typed_object, attribute_name)
 159             except AttributeError:
 160                 continue
 161             if not idl_type:
 162                 continue
 163             resolved_idl_type = idl_type.resolve_typedefs(self.typedefs)
 164             if depends_on_union_types(resolved_idl_type):
 165                 self.additional_includes.add(
 166                     self.info_provider.include_path_for_union_types)
 167             # Need to re-assign the attribute, not just mutate idl_type, since
 168             # type(idl_type) may change.
 169             setattr(typed_object, attribute_name, resolved_idl_type)
 170
 171     def visit_typed_object(self, typed_object):
 172         self._resolve_typedefs(typed_object)
 173
 174
 175 class CodeGeneratorBase(object):
 176     """Base class for v8 bindings generator and IDL dictionary impl generator"""
 177
 178     def __init__(self, info_provider, cache_dir, output_dir):
 179         self.info_provider = info_provider
 180         self.jinja_env = initialize_jinja_env(cache_dir)
 181         self.output_dir = output_dir
 182         self.typedef_resolver = TypedefResolver(info_provider)
 183         set_global_type_info(info_provider)
 184
 185     def generate_code(self, definitions, definition_name):
 186         """Returns .h/.cpp code as ((path, content)...)."""
 187         # Set local type info
 188         if not should_generate_code(definitions):
 189             return set()
 190
 191         IdlType.set_callback_functions(definitions.callback_functions.keys())
 192         # Resolve typedefs
 193         self.typedef_resolver.resolve(definitions, definition_name)
 194         return self.generate_code_internal(definitions, definition_name)
 195
 196     def generate_code_internal(self, definitions, definition_name):
 197         # This should be implemented in subclasses.
 198         raise NotImplementedError()
 199
 200
 201 class CodeGeneratorV8(CodeGeneratorBase):
 202     def __init__(self, info_provider, cache_dir, output_dir):
 203         CodeGeneratorBase.__init__(self, info_provider, cache_dir, output_dir)
 204
 205     def output_paths(self, definition_name):
 206         header_path = posixpath.join(self.output_dir,
 207                                      'V8%s.h' % definition_name)
 208         cpp_path = posixpath.join(self.output_dir, 'V8%s.cpp' % definition_name)
 209         return header_path, cpp_path
 210
 211     def generate_code_internal(self, definitions, definition_name):
 212         if definition_name in definitions.interfaces:
 213             return self.generate_interface_code(
 214                 definitions, definition_name,
 215                 definitions.interfaces[definition_name])
 216         if definition_name in definitions.dictionaries:
 217             return self.generate_dictionary_code(
 218                 definitions, definition_name,
 219                 definitions.dictionaries[definition_name])
 220         raise ValueError('%s is not in IDL definitions' % definition_name)
 221
 222     def generate_interface_code(self, definitions, interface_name, interface):
 223         # Store other interfaces for introspection
 224         interfaces.update(definitions.interfaces)
 225
 226         interface_info = self.info_provider.interfaces_info[interface_name]
 227         full_path = interface_info.get('full_path')
 228         component = idl_filename_to_component(full_path)
 229         include_paths = interface_info.get('dependencies_include_paths')
 230
 231         # Select appropriate Jinja template and contents function
 232         if interface.is_callback:
 233             header_template_filename = 'callback_interface.h'
 234             cpp_template_filename = 'callback_interface.cpp'
 235             interface_context = v8_callback_interface.callback_interface_context
 236         elif interface.is_partial:
 237             interface_context = v8_interface.interface_context
 238             header_template_filename = 'partial_interface.h'
 239             cpp_template_filename = 'partial_interface.cpp'
 240             interface_name += 'Partial'
 241             assert component == 'core'
 242             component = 'modules'
 243             include_paths = interface_info.get('dependencies_other_component_include_paths')
 244         else:
 245             header_template_filename = 'interface.h'
 246             cpp_template_filename = 'interface.cpp'
 247             interface_context = v8_interface.interface_context
 248
 249         template_context = interface_context(interface)
 250         includes.update(interface_info.get('cpp_includes', {}).get(component, set()))
 251         if not interface.is_partial and not is_testing_target(full_path):
 252             template_context['header_includes'].add(self.info_provider.include_path_for_export)
 253             template_context['exported'] = self.info_provider.specifier_for_export
 254         # Add the include for interface itself
 255         if IdlType(interface_name).is_typed_array:
 256             template_context['header_includes'].add('core/dom/DOMTypedArray.h')
 257         elif interface_info['include_path']:
 258             template_context['header_includes'].add(interface_info['include_path'])
 259
 260         header_template = self.jinja_env.get_template(header_template_filename)
 261         cpp_template = self.jinja_env.get_template(cpp_template_filename)
 262         header_text, cpp_text = render_template(
 263             include_paths, header_template, cpp_template, template_context,
 264             component)
 265         header_path, cpp_path = self.output_paths(interface_name)
 266         return (
 267             (header_path, header_text),
 268             (cpp_path, cpp_text),
 269         )
 270
 271     def generate_dictionary_code(self, definitions, dictionary_name,
 272                                  dictionary):
 273         interfaces_info = self.info_provider.interfaces_info
 274         header_template = self.jinja_env.get_template('dictionary_v8.h')
 275         cpp_template = self.jinja_env.get_template('dictionary_v8.cpp')
 276         interface_info = interfaces_info[dictionary_name]
 277         template_context = v8_dictionary.dictionary_context(
 278             dictionary, interfaces_info)
 279         include_paths = interface_info.get('dependencies_include_paths')
 280         # Add the include for interface itself
 281         if interface_info['include_path']:
 282             template_context['header_includes'].add(interface_info['include_path'])
 283         if not is_testing_target(interface_info.get('full_path')):
 284             template_context['header_includes'].add(self.info_provider.include_path_for_export)
 285             template_context['exported'] = self.info_provider.specifier_for_export
 286         header_text, cpp_text = render_template(
 287             include_paths, header_template, cpp_template, template_context)
 288         header_path, cpp_path = self.output_paths(dictionary_name)
 289         return (
 290             (header_path, header_text),
 291             (cpp_path, cpp_text),
 292         )
 293
 294
 295 class CodeGeneratorDictionaryImpl(CodeGeneratorBase):
 296     def __init__(self, info_provider, cache_dir, output_dir):
 297         CodeGeneratorBase.__init__(self, info_provider, cache_dir, output_dir)
 298
 299     def output_paths(self, definition_name, interface_info):
 300         output_dir = posixpath.join(self.output_dir,
 301                                     interface_info['relative_dir'])
 302         header_path = posixpath.join(output_dir, '%s.h' % definition_name)
 303         cpp_path = posixpath.join(output_dir, '%s.cpp' % definition_name)
 304         return header_path, cpp_path
 305
 306     def generate_code_internal(self, definitions, definition_name):
 307         if not definition_name in definitions.dictionaries:
 308             raise ValueError('%s is not an IDL dictionary')
 309         interfaces_info = self.info_provider.interfaces_info
 310         dictionary = definitions.dictionaries[definition_name]
 311         interface_info = interfaces_info[definition_name]
 312         header_template = self.jinja_env.get_template('dictionary_impl.h')
 313         cpp_template = self.jinja_env.get_template('dictionary_impl.cpp')
 314         template_context = v8_dictionary.dictionary_impl_context(
 315             dictionary, interfaces_info)
 316         include_paths = interface_info.get('dependencies_include_paths')
 317         # Add union containers header file to header_includes rather than
 318         # cpp file so that union containers can be used in dictionary headers.
 319         union_container_headers = [header for header in include_paths
 320                                    if header.find('UnionTypes') > 0]
 321         include_paths = [header for header in include_paths
 322                          if header not in union_container_headers]
 323         template_context['header_includes'].update(union_container_headers)
 324         if not is_testing_target(interface_info.get('full_path')):
 325             template_context['exported'] = self.info_provider.specifier_for_export
 326             template_context['header_includes'].add(self.info_provider.include_path_for_export)
 327         header_text, cpp_text = render_template(
 328             include_paths, header_template, cpp_template, template_context)
 329         header_path, cpp_path = self.output_paths(
 330             cpp_name(dictionary), interface_info)
 331         return (
 332             (header_path, header_text),
 333             (cpp_path, cpp_text),
 334         )
 335
 336
 337 class CodeGeneratorUnionType(object):
 338     """Generates union type container classes.
 339     This generator is different from CodeGeneratorV8 and
 340     CodeGeneratorDictionaryImpl. It assumes that all union types are already
 341     collected. It doesn't process idl files directly.
 342     """
 343     def __init__(self, info_provider, cache_dir, output_dir, target_component):
 344         self.info_provider = info_provider
 345         self.jinja_env = initialize_jinja_env(cache_dir)
 346         self.output_dir = output_dir
 347         self.target_component = target_component
 348         set_global_type_info(info_provider)
 349
 350     def generate_code(self):
 351         union_types = self.info_provider.union_types
 352         if not union_types:
 353             return ()
 354         header_template = self.jinja_env.get_template('union.h')
 355         cpp_template = self.jinja_env.get_template('union.cpp')
 356         template_context = v8_union.union_context(
 357             union_types, self.info_provider.interfaces_info)
 358         template_context['code_generator'] = module_pyname
 359         capitalized_component = self.target_component.capitalize()
 360         template_context['exported'] = self.info_provider.specifier_for_export
 361         template_context['header_filename'] = 'bindings/%s/v8/UnionTypes%s.h' % (
 362             self.target_component, capitalized_component)
 363         template_context['macro_guard'] = 'UnionType%s_h' % capitalized_component
 364         additional_header_includes = [self.info_provider.include_path_for_export]
 365
 366         # Add UnionTypesCore.h as a dependency when we generate modules union types
 367         # because we only generate union type containers which are used by both
 368         # core and modules in UnionTypesCore.h.
 369         # FIXME: This is an ad hoc workaround and we need a general way to
 370         # handle core <-> modules dependency.
 371         if self.target_component == 'modules':
 372             additional_header_includes.append(
 373                 'bindings/core/v8/UnionTypesCore.h')
 374
 375         template_context['header_includes'] = sorted(
 376             template_context['header_includes'] + additional_header_includes)
 377
 378         header_text = header_template.render(template_context)
 379         cpp_text = cpp_template.render(template_context)
 380         header_path = posixpath.join(self.output_dir,
 381                                      'UnionTypes%s.h' % capitalized_component)
 382         cpp_path = posixpath.join(self.output_dir,
 383                                   'UnionTypes%s.cpp' % capitalized_component)
 384         return (
 385             (header_path, header_text),
 386             (cpp_path, cpp_text),
 387         )
 388
 389
 390 def initialize_jinja_env(cache_dir):
 391     jinja_env = jinja2.Environment(
 392         loader=jinja2.FileSystemLoader(templates_dir),
 393         # Bytecode cache is not concurrency-safe unless pre-cached:
 394         # if pre-cached this is read-only, but writing creates a race condition.
 395         bytecode_cache=jinja2.FileSystemBytecodeCache(cache_dir),
 396         keep_trailing_newline=True,  # newline-terminate generated files
 397         lstrip_blocks=True,  # so can indent control flow tags
 398         trim_blocks=True)
 399     jinja_env.filters.update({
 400         'blink_capitalize': capitalize,
 401         'conditional': conditional_if_endif,
 402         'exposed': exposed_if,
 403         'runtime_enabled': runtime_enabled_if,
 404         })
 405     return jinja_env
 406
 407
 408 def generate_indented_conditional(code, conditional):
 409     # Indent if statement to level of original code
 410     indent = re.match(' *', code).group(0)
 411     return ('%sif (%s) {\n' % (indent, conditional) +
 412             '    %s\n' % '\n    '.join(code.splitlines()) +
 413             '%s}\n' % indent)
 414
 415
 416 # [Conditional]
 417 def conditional_if_endif(code, conditional_string):
 418     # Jinja2 filter to generate if/endif directive blocks
 419     if not conditional_string:
 420         return code
 421     return ('#if %s\n' % conditional_string +
 422             code +
 423             '#endif // %s\n' % conditional_string)
 424
 425
 426 # [Exposed]
 427 def exposed_if(code, exposed_test):
 428     if not exposed_test:
 429         return code
 430     return generate_indented_conditional(code, 'context && (%s)' % exposed_test)
 431
 432
 433 # [RuntimeEnabled]
 434 def runtime_enabled_if(code, runtime_enabled_function_name):
 435     if not runtime_enabled_function_name:
 436         return code
 437     return generate_indented_conditional(code, '%s()' % runtime_enabled_function_name)
 438
 439
 440 ################################################################################
 441
 442 def main(argv):
 443     # If file itself executed, cache templates
 444     try:
 445         cache_dir = argv[1]
 446         dummy_filename = argv[2]
 447     except IndexError as err:
 448         print 'Usage: %s CACHE_DIR DUMMY_FILENAME' % argv[0]
 449         return 1
 450
 451     # Cache templates
 452     jinja_env = initialize_jinja_env(cache_dir)
 453     template_filenames = [filename for filename in os.listdir(templates_dir)
 454                           # Skip .svn, directories, etc.
 455                           if filename.endswith(('.cpp', '.h'))]
 456     for template_filename in template_filenames:
 457         jinja_env.get_template(template_filename)
 458
 459     # Create a dummy file as output for the build system,
 460     # since filenames of individual cache files are unpredictable and opaque
 461     # (they are hashes of the template path, which varies based on environment)
 462     with open(dummy_filename, 'w') as dummy_file:
 463         pass  # |open| creates or touches the file
 464
 465
 466 if __name__ == '__main__':
 467     sys.exit(main(sys.argv))