components/README

   1 This directory is for features that are intended for reuse. Example use cases:
   2 - features that are shared by Chrome on iOS and other Chrome platforms (since
   3   the iOS port doesn't use src/chrome)
   4 - features that are shared between multiple embedders of content (e.g., Android
   5   WebView and Chrome)
   6 - features that are shared between Blink and the browser process
   7   * Note: It is also possible to place code shared between Blink and the
   8     browser process into //third_party/blink/common. The distinction comes
   9     down to (a) whether Blink is the owner of the code in question or a consumer
  10     of it and (b) whether the code in question is shared by Chrome on iOS as
  11     well. If the code is conceptually its own cross-process feature with Blink
  12     as a consumer, then //components can make sense. If it's conceptually
  13     Blink code, then third_party/blink/common likely makes more sense. (In the
  14     so-far hypothetical case where it's conceptually Blink code that is shared
  15     by iOS, raise the question on chromium-dev@, where the right folks will see
  16     it).
  17
  18 In general, if some code is used by a directory "foo" and things above "foo" in
  19 the dependency tree, the code should probably live in "foo".
  20
  21 By default, components can depend only on the lower layers of the Chromium
  22 codebase (e.g. base/, net/, etc.). Individual components may additionally allow
  23 dependencies on the content API and IPC; however, if such a component is used
  24 by Chrome for iOS (which does not use the content API or IPC), the component
  25 will have to be in the form of a layered component
  26 (http://www.chromium.org/developers/design-documents/layered-components-design).
  27
  28 Components that have bits of code that need to live in different
  29 processes (e.g. some code in the browser process, some in the renderer
  30 process, etc.) should separate the code into different subdirectories.
  31 Hence for a component named 'foo' you might end up with a structure
  32 like the following (assuming that foo is not used by iOS and thus does not
  33 need to be a layered component):
  34
  35 components/foo          - DEPS, OWNERS, foo.gypi
  36 components/foo/browser  - code that needs the browser process
  37 components/foo/common   - for e.g. IPC constants and such
  38 components/foo/renderer - code that needs renderer process
  39
  40 These subdirectories should have DEPS files with the relevant
  41 restrictions in place, i.e. only components/*/browser should
  42 be allowed to #include from content/public/browser.
  43
  44 Note that there may also be an 'android' subdir, with a Java source
  45 code structure underneath it where the package name is
  46 org.chromium.components.foo, and with subdirs after 'foo'
  47 to illustrate process, e.g. 'browser' or 'renderer':
  48
  49 components/foo/android/OWNERS, DEPS
  50 components/foo/android/java/src/org/chromium/components/foo/browser/
  51 components/foo/android/javatests/src/org/chromium/components/foo/browser/
  52
  53 Code in a component should be placed in a namespace corresponding to
  54 the name of the component; e.g. for a component living in
  55 //components/foo, code in that component should be in the foo::
  56 namespace.