content/README.md

   1 # Content module
   2
   3 ## High-level overview
   4 The "content" module is located in `src/content`, and is the core code needed to
   5 render a page using a multi-process sandboxed browser. It includes all the web
   6 platform features (i.e. HTML5) and GPU acceleration. It does not include Chrome
   7 features, e.g. extensions/autofill/spelling etc.
   8
   9 ## Motivation
  10 As the Chromium code has grown, features inevitably hooked into the wrong
  11 places, causing layering violations and dependencies that shouldn't exist. It's
  12 been hard for developers to figure out what the "best" way is because the APIs
  13 (when they existed) and features were together in the same directory. To avoid
  14 this happening, and to add a clear separation between the core pieces of the
  15 code that render a page using a multi-process browser, consensus was reached to
  16 move the core Chrome code into `src/content` ([content not
  17 chrome](http://blog.chromium.org/2008/10/content-not-chrome.html) :) ).
  18
  19 ## content vs chrome
  20 `content` should only contain code that is required to implement the web
  21 platform. Generally, a feature belongs in this category if and only if all of
  22 the following are true:
  23
  24 - Its launch is tracked on the <https://chromestatus.com/> dashboard.
  25 - It has an associated spec.
  26 - It is going through the [feature development
  27   lifecycle](https://www.chromium.org/blink/launching-features).
  28
  29 In contrast, many features that are common to modern web browsers do not satisfy
  30 these criteria and thus, are not implemented in `content`. A non-exhaustive
  31 list:
  32
  33 - Extensions
  34 - NaCl
  35 - SpellCheck
  36 - Autofill
  37 - Sync
  38 - Safe Browsing
  39 - Translate
  40
  41 Instead, these features are implemented in `chrome`, while `content` only
  42 provides generic extension points that allow these features to subscribe to the
  43 events they require. Some features will require adding new extension points: for
  44 more information, see [How to Add New Features (without bloating
  45 RenderView/RenderViewHost/WebContents)](https://www.chromium.org/developers/design-documents/multi-process-architecture/how-to-add-new-features).
  46
  47 Finally, there are a number of browser features that require interaction with
  48 online services supplied by the vendor, e.g. from the above list, Safe Browsing,
  49 Translate, Sync, and Autofill all require various network services to function.
  50 The `chrome` layer is the natural place to encapsulate that vendor-specific
  51 integration behavior. For the rare cases where a web platform feature
  52 implemented in `content` has a dependency on a network service (e.g. the network
  53 location service used by Geolocation), `content` should provide a way for the
  54 embedder to inject an endpoint (e.g. `chrome` might provide the service URL to
  55 use). The `content` module itself must remain generic, with no hardcoded
  56 vendor-specific logic.
  57
  58 ## Architectural Diagram
  59 ![Chrome browser depends on content, which as a whole depends on Chromium's
  60   low-level libraries and on the constituent parts of
  61   //content.](./architecture.png)
  62
  63 See an older diagram at: https://www.chromium.org/developers/content-module.
  64
  65 The diagram illustrates the layering of the different modules. A module can
  66 include code directly from lower modules. However, a module can not include code
  67 from a module that is higher than it.  This is enforced through DEPS rules.
  68 Modules can implement embedder APIs so that modules lower than them can call
  69 them. Examples of these APIs are the WebKit API and the Content API.
  70
  71 ## Content API
  72 The [Content API](public/README.md) is how code in content can indirectly call
  73 Chrome. Where possible, Chrome features try to hook in by filtering IPCs and
  74 listening to events per [How to Add New Features (without bloating
  75 RenderView/RenderViewHost/WebContents)](https://www.chromium.org/developers/design-documents/multi-process-architecture/how-to-add-new-features).
  76 When there isn't enough context (i.e.  callback from WebKit) or when the
  77 callback is a one-off, we have a `ContentClient` interface that the embedder
  78 (Chrome) implements. `ContentClient` is available in all processes. Some
  79 processes also have their own callback API as well, i.e.
  80 `ContentBrowserClient/ContentRendererClient/ContentPluginClient`.
  81
  82 ## Status and Roadmap
  83 The current status is `content` doesn't depend on chrome at all (see the meta
  84 [bug](https://bugs.chromium.org/p/chromium/issues/detail?id=76697) and all bugs
  85 it depends on). We now have a basic browser built on top of `content`
  86 ("`content_shell`") that renders pages using `content` on all platforms. This
  87 allow developers working on the web platform and core code to only have to
  88 build/test content, instead of all of chrome.
  89
  90 We have a separate target for `content`'s unit tests in `content_unittests`, and
  91 integration tests in `content_browsertests`.
  92
  93 `content` is build at a separate dll to speed up the build.
  94
  95 We've created an API around `content`, similar to our WebKit API. This isolates
  96 embedders from content's inner workings, and makes it clear to people working on
  97 content which methods are used by embedders.
  98
  99 ## Further documentation
 100
 101 * [Bluetooth](browser/bluetooth/README.md)