1 # Copyright (C) 2013 Google Inc. All rights reserved.
3 # Redistribution and use in source and binary forms, with or without
4 # modification, are permitted provided that the following conditions are
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
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.
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.
29 """Generate Blink V8 bindings (.h and .cpp files).
31 If run itself, caches Jinja templates (and creates dummy file for build,
32 since cache filenames are unpredictable and opaque).
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.
40 Input: An object of class IdlDefinitions, containing an IDL interface X
41 Output: V8X.h and V8X.cpp
43 Design doc: http://www.chromium.org/developers/design-documents/idl-compiler
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'
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)
74 from idl_types import IdlType
75 import v8_callback_interface
77 from v8_globals import includes, interfaces
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
85 def render_template(include_paths, header_template, cpp_template,
86 template_context, component=None):
87 template_context['code_generator'] = module_pyname
89 # Add includes for any dependencies
90 template_context['header_includes'] = sorted(
91 template_context['header_includes'])
93 for include_path in include_paths:
95 dependency = idl_filename_to_component(include_path)
96 assert is_valid_component_dependency(component, dependency)
97 includes.add(include_path)
99 template_context['cpp_includes'] = sorted(includes)
101 header_text = header_template.render(template_context)
102 cpp_text = cpp_template.render(template_context)
103 return header_text, cpp_text
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'])
116 class CodeGeneratorBase(object):
117 """Base class for v8 bindings generator and IDL dictionary impl generator"""
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)
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)
134 def generate_code_internal(self, definitions, definition_name):
135 # This should be implemented in subclasses.
136 raise NotImplementedError()
139 class CodeGeneratorV8(CodeGeneratorBase):
140 def __init__(self, interfaces_info, cache_dir, output_dir):
141 CodeGeneratorBase.__init__(self, interfaces_info, cache_dir, output_dir)
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
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)
160 def generate_interface_code(self, definitions, interface_name, interface):
161 # Store other interfaces for introspection
162 interfaces.update(definitions.interfaces)
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')
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')
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)
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')
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,
198 header_path, cpp_path = self.output_paths(interface_name)
200 (header_path, header_text),
201 (cpp_path, cpp_text),
204 def generate_dictionary_code(self, definitions, dictionary_name,
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)
217 (header_path, header_text),
218 (cpp_path, cpp_text),
222 class CodeGeneratorDictionaryImpl(CodeGeneratorBase):
223 def __init__(self, interfaces_info, cache_dir, output_dir):
224 CodeGeneratorBase.__init__(self, interfaces_info, cache_dir, output_dir)
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
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)
248 (header_path, header_text),
249 (cpp_path, cpp_text),
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.
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)
266 def generate_code(self, union_types):
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)
286 (header_path, header_text),
287 (cpp_path, cpp_text),
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
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,
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()) +
319 def conditional_if_endif(code, conditional_string):
320 # Jinja2 filter to generate if/endif directive blocks
321 if not conditional_string:
323 return ('#if %s\n' % conditional_string +
325 '#endif // %s\n' % conditional_string)
329 def exposed_if(code, exposed_test):
332 return generate_indented_conditional(code, 'context && (%s)' % exposed_test)
335 # [PerContextEnabled]
336 def per_context_enabled_if(code, per_context_enabled_function):
337 if not per_context_enabled_function:
339 return generate_indented_conditional(code, 'context && context->isDocument() && %s(toDocument(context))' % per_context_enabled_function)
343 def runtime_enabled_if(code, runtime_enabled_function_name):
344 if not runtime_enabled_function_name:
346 return generate_indented_conditional(code, '%s()' % runtime_enabled_function_name)
349 ################################################################################
352 # If file itself executed, cache templates
355 dummy_filename = argv[2]
356 except IndexError as err:
357 print 'Usage: %s CACHE_DIR DUMMY_FILENAME' % argv[0]
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)
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
375 if __name__ == '__main__':
376 sys.exit(main(sys.argv))