mozwebidlcodegen package

Module contents

class mozwebidlcodegen.BuildResult

Bases: object

Represents the result of processing WebIDL files.

This holds a summary of output file generation during code generation.

class mozwebidlcodegen.WebIDLCodegenManager(config_path, webidl_root, inputs, exported_header_dir, codegen_dir, state_path, cache_dir=None, make_deps_path=None, make_deps_target=None)

Bases: LoggingMixin

Manages all code generation around WebIDL.

To facilitate testing, this object is meant to be generic and reusable. Paths, etc should be parameters and not hardcoded.

GLOBAL_DECLARE_FILES = {'BindingNames.h', 'GeneratedAtomList.h', 'GeneratedEventList.h', 'PrototypeList.h', 'RegisterBindings.h', 'RegisterShadowRealmBindings.h', 'RegisterWorkerBindings.h', 'RegisterWorkerDebuggerBindings.h', 'RegisterWorkletBindings.h', 'UnionTypes.h', 'WebIDLPrefs.h', 'WebIDLSerializable.h'}
GLOBAL_DEFINE_FILES = {'BindingNames.cpp', 'PrototypeList.cpp', 'RegisterBindings.cpp', 'RegisterShadowRealmBindings.cpp', 'RegisterWorkerBindings.cpp', 'RegisterWorkerDebuggerBindings.cpp', 'RegisterWorkletBindings.cpp', 'UnionTypes.cpp', 'WebIDLPrefs.cpp', 'WebIDLSerializable.cpp'}
property config
expected_build_output_files()

Obtain the set of files generate_build_files() should write.

generate_build_files(*, processes=None)

Generate files required for the build.

This function is in charge of generating all the .h/.cpp files derived from input .webidl files. Please note that there are build actions required to produce .webidl files and these build actions are explicitly not captured here: this function assumes all .webidl files are present and up to date.

This routine is called as part of the build to ensure files that need to exist are present and up to date. This routine may not be called if the build dependencies (generated as a result of calling this the first time) say everything is up to date.

Because reprocessing outputs for every .webidl on every invocation is expensive, we only regenerate the minimal set of files on every invocation. The rules for deciding what needs done are roughly as follows:

  1. If any .webidl changes, reparse all .webidl files and regenerate the global derived files. Only regenerate output files (.h/.cpp) impacted by the modified .webidl files.

  2. If an non-.webidl dependency (Python files, config file) changes, assume everything is out of date and regenerate the world. This is because changes in those could globally impact every output file.

  3. If an output file is missing, ensure it is present by performing necessary regeneration.

if processes is set to None, run in parallel using the multiprocess.Pool default. If set to 1, don’t use extra processes.

generate_example_files(interface)

Generates example files for a given interface.

class mozwebidlcodegen.WebIDLCodegenManagerState(fh=None)

Bases: dict

Holds state for the WebIDL code generation manager.

State is currently just an extended dict. The internal implementation of state should be considered a black box to everyone except WebIDLCodegenManager. But we’ll still document it.

Any set stored in this dict should be copied and sorted in the dump() method.

Fields:

version

The integer version of the format. This is to detect incompatible changes between state. It should be bumped whenever the format changes or semantics change.

webidls

A dictionary holding information about every known WebIDL input. Keys are the basenames of input WebIDL files. Values are dicts of metadata. Keys in those dicts are:

  • filename - The full path to the input filename.

  • inputs - A set of full paths to other webidl files this webidl depends on.

  • outputs - Set of full output paths that are created/derived from this file.

  • sha1 - The hexidecimal SHA-1 of the input filename from the last processing time.

global_inputs

A dictionary defining files that influence all processing. Keys are full filenames. Values are hexidecimal SHA-1 from the last processing time.

dictionaries_convertible_to_js

A set of names of dictionaries that are convertible to JS.

dictionaries_convertible_from_js

A set of names of dictionaries that are convertible from JS.

VERSION = 3
dump(fh)

Dump serialized state to a file handle.

class mozwebidlcodegen.WebIDLPool(GeneratorState, *, processes=None)

Bases: object

Distribute generation load across several processes, avoiding redundant state copies.

GeneratorState = None
run(filenames)
mozwebidlcodegen.create_build_system_manager(topsrcdir=None, topobjdir=None, dist_dir=None)

Create a WebIDLCodegenManager for use by the build system.