components/README

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