Ben Murdoch | 591b958 | 2013-07-10 11:41:44 +0100 | [diff] [blame] | 1 | Blink Public API |
| 2 | ================ |
| 3 | |
| 4 | This directory contains the public API for Blink. The API consists of a number |
| 5 | of C++ header files, scripts, and GYP build files. We consider all other files |
| 6 | in Blink to be implementation details, which are subject to change at any time |
| 7 | without notice. |
| 8 | |
| 9 | The primary consumer of this API is Chromium's Content layer. If you are |
| 10 | interested in using Blink, please consider interfacing with Blink via the |
| 11 | Content layer rather than interfacing directly with this API. |
| 12 | |
| 13 | Compatibility |
| 14 | ------------- |
| 15 | |
| 16 | The API does not support binary compatibility. Instead, the API is intended to |
| 17 | insulate the rest of the Chromium project from internal changes to Blink. Over |
| 18 | time, the API is likely to evolve in source-incompatible ways as Chromium's and |
| 19 | Blink's needs change. |
| 20 | |
| 21 | Organization |
| 22 | ------------ |
| 23 | |
| 24 | The API is organized into three parts: |
| 25 | |
| 26 | - public/platform |
| 27 | - public/web |
| 28 | - public/testing |
| 29 | |
| 30 | The public/platform directory defines an abstract platform upon which Blink |
| 31 | runs. Rather than communicating directly with the underlying operating system, |
| 32 | Blink is designed to run in a sandbox and interacts with the operating system |
| 33 | via the platform API. The central interface in this part of the API is |
| 34 | Platform, which is a pure virtual interface from which Blink obtains many other |
| 35 | interfaces. |
| 36 | |
| 37 | The public/web directory defines an interface to Blink's implementation of the |
| 38 | web platform, including the Document Object Model (DOM). The central interface |
| 39 | in this part of the API is WebView, which is a good starting point for |
| 40 | exploring the API. |
| 41 | |
Ben Murdoch | 0019e4e | 2013-07-18 11:57:54 +0100 | [diff] [blame] | 42 | Note that public/platform should not depend on public/web. |
| 43 | |
Ben Murdoch | 591b958 | 2013-07-10 11:41:44 +0100 | [diff] [blame] | 44 | The public/testing directory defines an interface for testing Blink. You can |
| 45 | use this part of the API to load the TestRunner module used in Blink's test |
| 46 | suite. |
| 47 | |
| 48 | Basic Types |
| 49 | ----------- |
| 50 | |
| 51 | The API does not use STL types, except for a small number of STL types that are |
| 52 | used internally by Blink (e.g., std::pair). Instead, we use WTF containers to |
| 53 | implement the API. |
| 54 | |
| 55 | The API uses some internal types (e.g., WebCore::Node). Typically, these types |
| 56 | are forward declared and are opaque to consumers of the API. In other cases, |
| 57 | the full definitions are available behind the WEBKIT_IMPLEMENTATION |
| 58 | preprocessor macro. In both cases, we continue to regard these internal types |
| 59 | as implementation details of Blink, and consumers of the API should not rely |
| 60 | upon these types. |
| 61 | |
| 62 | Similarly, the API uses STL types outside of the WEBKIT_IMPLEMENTATION |
| 63 | preprocessor macro, which is for the convenience of the consumer. |
| 64 | |
| 65 | Contact Information |
| 66 | ------------------- |
| 67 | |
| 68 | The public API also contains an OWNERS file, which lists a number of people who |
| 69 | are knowledgeable about the API. If you have questions or comments about the |
| 70 | API that might be of general interest to the Blink community at large, please |
| 71 | consider directing your inquiry to blink-dev@chromium.org rather than to the |
| 72 | OWNERS specifically. |