src/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 import idl_types
  74 from idl_types import IdlType
  75 import v8_callback_interface
  76 import v8_dictionary
  77 from v8_globals import includes, interfaces
  78 import v8_interface
  79 import v8_types
  80 import v8_union
  81 from v8_utilities import capitalize, cpp_name, conditional_string, v8_class_name
  82 from utilities import KNOWN_COMPONENTS, idl_filename_to_component, is_valid_component_dependency
  83
  84
  85 def render_template(include_paths, header_template, cpp_template,
  86                     template_context, component=None):
  87     template_context['code_generator'] = module_pyname
  88
  89     # Add includes for any dependencies
  90     template_context['header_includes'] = sorted(
  91         template_context['header_includes'])
  92
  93     for include_path in include_paths:
  94         if component:
  95             dependency = idl_filename_to_component(include_path)
  96             assert is_valid_component_dependency(component, dependency)
  97         includes.add(include_path)
  98
  99     template_context['cpp_includes'] = sorted(includes)
 100
 101     header_text = header_template.render(template_context)
 102     cpp_text = cpp_template.render(template_context)
 103     return header_text, cpp_text
 104
 105
 106 def set_global_type_info(interfaces_info):
 107     idl_types.set_ancestors(interfaces_info['ancestors'])
 108     IdlType.set_callback_interfaces(interfaces_info['callback_interfaces'])
 109     IdlType.set_dictionaries(interfaces_info['dictionaries'])
 110     IdlType.set_implemented_as_interfaces(interfaces_info['implemented_as_interfaces'])
 111     IdlType.set_garbage_collected_types(interfaces_info['garbage_collected_interfaces'])
 112     IdlType.set_will_be_garbage_collected_types(interfaces_info['will_be_garbage_collected_interfaces'])
 113     v8_types.set_component_dirs(interfaces_info['component_dirs'])
 114
 115
 116 class CodeGeneratorBase(object):
 117     """Base class for v8 bindings generator and IDL dictionary impl generator"""
 118
 119     def __init__(self, interfaces_info, cache_dir, output_dir):
 120         interfaces_info = interfaces_info or {}
 121         self.interfaces_info = interfaces_info
 122         self.jinja_env = initialize_jinja_env(cache_dir)
 123         self.output_dir = output_dir
 124         set_global_type_info(interfaces_info)
 125
 126     def generate_code(self, definitions, definition_name):
 127         """Returns .h/.cpp code as ((path, content)...)."""
 128         # Set local type info
 129         IdlType.set_callback_functions(definitions.callback_functions.keys())
 130         IdlType.set_enums((enum.name, enum.values)
 131                           for enum in definitions.enumerations.values())
 132         return self.generate_code_internal(definitions, definition_name)
 133
 134     def generate_code_internal(self, definitions, definition_name):
 135         # This should be implemented in subclasses.
 136         raise NotImplementedError()
 137
 138
 139 class CodeGeneratorV8(CodeGeneratorBase):
 140     def __init__(self, interfaces_info, cache_dir, output_dir):
 141         CodeGeneratorBase.__init__(self, interfaces_info, cache_dir, output_dir)
 142
 143     def output_paths(self, definition_name):
 144         header_path = posixpath.join(self.output_dir,
 145                                      'V8%s.h' % definition_name)
 146         cpp_path = posixpath.join(self.output_dir, 'V8%s.cpp' % definition_name)
 147         return header_path, cpp_path
 148
 149     def generate_code_internal(self, definitions, definition_name):
 150         if definition_name in definitions.interfaces:
 151             return self.generate_interface_code(
 152                 definitions, definition_name,
 153                 definitions.interfaces[definition_name])
 154         if definition_name in definitions.dictionaries:
 155             return self.generate_dictionary_code(
 156                 definitions, definition_name,
 157                 definitions.dictionaries[definition_name])
 158         raise ValueError('%s is not in IDL definitions' % definition_name)
 159
 160     def generate_interface_code(self, definitions, interface_name, interface):
 161         # Store other interfaces for introspection
 162         interfaces.update(definitions.interfaces)
 163
 164         interface_info = self.interfaces_info[interface_name]
 165         component = idl_filename_to_component(
 166             interface_info.get('full_path'))
 167         include_paths = interface_info.get('dependencies_include_paths')
 168
 169         # Select appropriate Jinja template and contents function
 170         if interface.is_callback:
 171             header_template_filename = 'callback_interface.h'
 172             cpp_template_filename = 'callback_interface.cpp'
 173             interface_context = v8_callback_interface.callback_interface_context
 174         elif interface.is_partial:
 175             interface_context = v8_interface.interface_context
 176             header_template_filename = 'partial_interface.h'
 177             cpp_template_filename = 'partial_interface.cpp'
 178             interface_name += 'Partial'
 179             assert component == 'core'
 180             component = 'modules'
 181             include_paths = interface_info.get('dependencies_other_component_include_paths')
 182         else:
 183             header_template_filename = 'interface.h'
 184             cpp_template_filename = 'interface.cpp'
 185             interface_context = v8_interface.interface_context
 186         header_template = self.jinja_env.get_template(header_template_filename)
 187         cpp_template = self.jinja_env.get_template(cpp_template_filename)
 188
 189         template_context = interface_context(interface)
 190         # Add the include for interface itself
 191         if IdlType(interface_name).is_typed_array:
 192             template_context['header_includes'].add('core/dom/DOMTypedArray.h')
 193         else:
 194             template_context['header_includes'].add(interface_info['include_path'])
 195         header_text, cpp_text = render_template(
 196             include_paths, header_template, cpp_template, template_context,
 197             component)
 198         header_path, cpp_path = self.output_paths(interface_name)
 199         return (
 200             (header_path, header_text),
 201             (cpp_path, cpp_text),
 202         )
 203
 204     def generate_dictionary_code(self, definitions, dictionary_name,
 205                                  dictionary):
 206         header_template = self.jinja_env.get_template('dictionary_v8.h')
 207         cpp_template = self.jinja_env.get_template('dictionary_v8.cpp')
 208         template_context = v8_dictionary.dictionary_context(dictionary)
 209         interface_info = self.interfaces_info[dictionary_name]
 210         include_paths = interface_info.get('dependencies_include_paths')
 211         # Add the include for interface itself
 212         template_context['header_includes'].add(interface_info['include_path'])
 213         header_text, cpp_text = render_template(
 214             include_paths, header_template, cpp_template, template_context)
 215         header_path, cpp_path = self.output_paths(dictionary_name)
 216         return (
 217             (header_path, header_text),
 218             (cpp_path, cpp_text),
 219         )
 220
 221
 222 class CodeGeneratorDictionaryImpl(CodeGeneratorBase):
 223     def __init__(self, interfaces_info, cache_dir, output_dir):
 224         CodeGeneratorBase.__init__(self, interfaces_info, cache_dir, output_dir)
 225
 226     def output_paths(self, definition_name, interface_info):
 227         output_dir = posixpath.join(self.output_dir,
 228                                     interface_info['relative_dir'])
 229         header_path = posixpath.join(output_dir, '%s.h' % definition_name)
 230         cpp_path = posixpath.join(output_dir, '%s.cpp' % definition_name)
 231         return header_path, cpp_path
 232
 233     def generate_code_internal(self, definitions, definition_name):
 234         if not definition_name in definitions.dictionaries:
 235             raise ValueError('%s is not an IDL dictionary')
 236         dictionary = definitions.dictionaries[definition_name]
 237         interface_info = self.interfaces_info[definition_name]
 238         header_template = self.jinja_env.get_template('dictionary_impl.h')
 239         cpp_template = self.jinja_env.get_template('dictionary_impl.cpp')
 240         template_context = v8_dictionary.dictionary_impl_context(
 241             dictionary, self.interfaces_info)
 242         include_paths = interface_info.get('dependencies_include_paths')
 243         header_text, cpp_text = render_template(
 244             include_paths, header_template, cpp_template, template_context)
 245         header_path, cpp_path = self.output_paths(
 246             definition_name, interface_info)
 247         return (
 248             (header_path, header_text),
 249             (cpp_path, cpp_text),
 250         )
 251
 252
 253 class CodeGeneratorUnionType(object):
 254     """Generates union type container classes.
 255     This generator is different from CodeGeneratorV8 and
 256     CodeGeneratorDictionaryImpl. It assumes that all union types are already
 257     collected. It doesn't process idl files directly.
 258     """
 259     def __init__(self, interfaces_info, cache_dir, output_dir, target_component):
 260         self.interfaces_info = interfaces_info
 261         self.jinja_env = initialize_jinja_env(cache_dir)
 262         self.output_dir = output_dir
 263         self.target_component = target_component
 264         set_global_type_info(interfaces_info)
 265
 266     def generate_code(self, union_types):
 267         if not union_types:
 268             return ()
 269         header_template = self.jinja_env.get_template('union.h')
 270         cpp_template = self.jinja_env.get_template('union.cpp')
 271         template_context = v8_union.union_context(
 272             sorted(union_types, key=lambda union_type: union_type.name),
 273             self.interfaces_info)
 274         template_context['code_generator'] = module_pyname
 275         capitalized_component = self.target_component.capitalize()
 276         template_context['header_filename'] = 'bindings/%s/v8/UnionTypes%s.h' % (
 277             self.target_component, capitalized_component)
 278         template_context['macro_guard'] = 'UnionType%s_h' % capitalized_component
 279         header_text = header_template.render(template_context)
 280         cpp_text = cpp_template.render(template_context)
 281         header_path = posixpath.join(self.output_dir,
 282                                      'UnionTypes%s.h' % capitalized_component)
 283         cpp_path = posixpath.join(self.output_dir,
 284                                   'UnionTypes%s.cpp' % capitalized_component)
 285         return (
 286             (header_path, header_text),
 287             (cpp_path, cpp_text),
 288         )
 289
 290
 291 def initialize_jinja_env(cache_dir):
 292     jinja_env = jinja2.Environment(
 293         loader=jinja2.FileSystemLoader(templates_dir),
 294         # Bytecode cache is not concurrency-safe unless pre-cached:
 295         # if pre-cached this is read-only, but writing creates a race condition.
 296         bytecode_cache=jinja2.FileSystemBytecodeCache(cache_dir),
 297         keep_trailing_newline=True,  # newline-terminate generated files
 298         lstrip_blocks=True,  # so can indent control flow tags
 299         trim_blocks=True)
 300     jinja_env.filters.update({
 301         'blink_capitalize': capitalize,
 302         'conditional': conditional_if_endif,
 303         'exposed': exposed_if,
 304         'per_context_enabled': per_context_enabled_if,
 305         'runtime_enabled': runtime_enabled_if,
 306         })
 307     return jinja_env
 308
 309
 310 def generate_indented_conditional(code, conditional):
 311     # Indent if statement to level of original code
 312     indent = re.match(' *', code).group(0)
 313     return ('%sif (%s) {\n' % (indent, conditional) +
 314             '    %s\n' % '\n    '.join(code.splitlines()) +
 315             '%s}\n' % indent)
 316
 317
 318 # [Conditional]
 319 def conditional_if_endif(code, conditional_string):
 320     # Jinja2 filter to generate if/endif directive blocks
 321     if not conditional_string:
 322         return code
 323     return ('#if %s\n' % conditional_string +
 324             code +
 325             '#endif // %s\n' % conditional_string)
 326
 327
 328 # [Exposed]
 329 def exposed_if(code, exposed_test):
 330     if not exposed_test:
 331         return code
 332     return generate_indented_conditional(code, 'context && (%s)' % exposed_test)
 333
 334
 335 # [PerContextEnabled]
 336 def per_context_enabled_if(code, per_context_enabled_function):
 337     if not per_context_enabled_function:
 338         return code
 339     return generate_indented_conditional(code, 'context && context->isDocument() && %s(toDocument(context))' % per_context_enabled_function)
 340
 341
 342 # [RuntimeEnabled]
 343 def runtime_enabled_if(code, runtime_enabled_function_name):
 344     if not runtime_enabled_function_name:
 345         return code
 346     return generate_indented_conditional(code, '%s()' % runtime_enabled_function_name)
 347
 348
 349 ################################################################################
 350
 351 def main(argv):
 352     # If file itself executed, cache templates
 353     try:
 354         cache_dir = argv[1]
 355         dummy_filename = argv[2]
 356     except IndexError as err:
 357         print 'Usage: %s CACHE_DIR DUMMY_FILENAME' % argv[0]
 358         return 1
 359
 360     # Cache templates
 361     jinja_env = initialize_jinja_env(cache_dir)
 362     template_filenames = [filename for filename in os.listdir(templates_dir)
 363                           # Skip .svn, directories, etc.
 364                           if filename.endswith(('.cpp', '.h'))]
 365     for template_filename in template_filenames:
 366         jinja_env.get_template(template_filename)
 367
 368     # Create a dummy file as output for the build system,
 369     # since filenames of individual cache files are unpredictable and opaque
 370     # (they are hashes of the template path, which varies based on environment)
 371     with open(dummy_filename, 'w') as dummy_file:
 372         pass  # |open| creates or touches the file
 373
 374
 375 if __name__ == '__main__':
 376     sys.exit(main(sys.argv))