-
Notifications
You must be signed in to change notification settings - Fork 48
Architectural Overview
Or, how we generate all this stuff
The chrome.dart provides an interface to the Chrome Packages Apps and Extensions APIs. The package is automatically generated from the JSON and IDL specification files (https://github.com/dart-gde/chrome.dart/tree/master/idl). Some docs on how to rev the spec are available here: https://github.com/dart-gde/chrome.dart/blob/master/idl_readme.txt. After the spec files have been updated, the Dart code can be regenerated by running tool/gen_apis.dart. When generated, it is useful to use git diff to compare the newly generated code with the last committed version of the code.
There are two different files formats for specifying the Chrome Apps and Extensions APIs. The older format uses JSON (example), and the newer format uses WebIDL (example). Our understanding is that older APIS, originally defined in JSON, continue to be maintained in that format. Newer APIs are spec'ed out in WebIDL.
The parsing and code gen. code lives here: https://github.com/dart-gde/chrome.dart/tree/master/tool. In short, the json files are parsed into a JSON specific model, and the IDL files parsed into an IDL specific model. These two models are designed to map well to their respective source formats; as in, very little semantic translation has to be done when parsing the json or idl. Both JSON and WebIDL formats are then translated into a third model (https://github.com/dart-gde/chrome.dart/blob/master/tool/chrome_model.dart), the Chrome model. This model is semantically very close to the final source code representation. The source code is then generated from this third model.
The generated source lives in https://github.com/dart-gde/chrome.dart/tree/master/lib/gen, with the two entry points (chrome_app.dart and chrome_ext.dart) in https://github.com/dart-gde/chrome.dart/tree/master/lib. This generated code uses JS interop (via dart:js). One of the principles of the code generator was to produce code that would rival hand-written code in terms of readability. An example of this generated code is here: https://github.com/dart-gde/chrome.dart/blob/master/lib/gen/alarms.dart. There are some mechanisms for hand-patching the generated code and having it persist automatically between generations. One hand-patched file exists here: https://github.com/dart-gde/chrome.dart/blob/master/lib/gen/app_patch.dart.