components/component_updater/README.md

   1 # Component Updater
   2
   3 [TOC]
   4
   5 ## Overview
   6 The Component Updater is a piece of Chrome responsible for updating other pieces
   7 of Chrome. It runs in the browser process and communicates with a set of servers
   8 using the [Omaha](https://github.com/google/omaha) protocol to find the latest
   9 versions of components, download them, and register them with the rest of
  10 Chrome.
  11
  12 The primary benefit of components is that they can be updated without an update
  13 to Chrome itself, which allows them to have faster (or desynchronized) release
  14 cadences, lower bandwidth consumption, and avoids bloat in the (already sizable)
  15 Chrome installer. The primary drawback is that they require Chrome to tolerate
  16 their absence in a sane way.
  17
  18 In the normal configuration, the component updater registers all components
  19 during (or close to) browser start-up, and then begins checking for updates six
  20 minutes later, with substantial pauses between successive update application.
  21
  22 ## Terminology
  23 For the purposes of this document:
  24
  25  * A `component` is any element of Chrome's core functionality that is sometimes
  26    delivered by the component updater separately from the browser itself,
  27    usually as a dynamically-linked library or data file.
  28  * A `crx file` is any file in the
  29    [CRX package format](../crx_file/README.md).
  30
  31 ## Adding New Components
  32 This document covers the work that must be done on the client side. Additional
  33 work is necessary to integrate with the Omaha servers, and is covered in
  34 [Google-internal documentation](http://go/newchromecomponent).
  35
  36 This assumes you've already done the hard work of splitting your functionality
  37 out into a dynamically-linked library or data file.
  38
  39 ### Create a CRX Package Signing Key & Manifest (Non-Google)
  40 All components are delivered as CRX files (signed ZIP archives). You need to
  41 create a signing key. If you are a Googler, follow the instructions at
  42 http://go/newchromecomponent for maximum key security. Otherwise, you can
  43 create an RSA key pair using `openssl` or a similar tool.
  44
  45 You will additionally need to create a manifest.json file. If nothing else, the
  46 manifest file must specify the component's version and name. If you plan to
  47 release the component using Google infrastructure, this file can be generated
  48 for you automatically.
  49
  50 ### Writing an Installer
  51 The "installer" is a piece of Chrome code that the component updater will run to
  52 install or update the component. Installers live at
  53 `src/chrome/browser/component_updater`.
  54
  55 You will need the SHA256 hash of the public key generated in the previous step,
  56 as well as the CRX ID, which consists of the first half (128 bits) of that hash,
  57 rendered as hexadecimal using the characters `a-p` (rather than `0-9a-f`).
  58
  59 New components should use
  60 [`component_installer`](component_installer.h)
  61 if possible, as this provides you with transparent differential updates, version
  62 management, and more. You must provide a `ComponentInstallerPolicy` object to
  63 a new `ComponentInstaller`.
  64 [file\_type\_policies\_component\_installer.cc](../../chrome/browser/component_updater/file_type_policies_component_installer.cc)
  65 is a good example to work from.
  66
  67 Components need to be registered with the component updater. This is done in
  68 [RegisterComponentsForUpdate](https://cs.chromium.org/chromium/src/chrome/browser/chrome_browser_main.cc).
  69
  70 ### Bundle with the Chrome Installer (Optional, not recommended)
  71 If you need the guarantee that some implementation of your component is always
  72 available, you must bundle a component implementation with the browser itself.
  73 If you are using `ComponentInstaller`, you simply need to make sure that
  74 your component implementation (and a corresponding manifest.json file) are
  75 written to DIR\_COMPONENTS as part of the build. The manifest.json file must
  76 state the version of this component implementation, and the files must be
  77 bitwise identical to the contents of any update CRX with that version for that
  78 platform, as the system will attempt to apply differential updates over these
  79 files.
  80
  81 This option is not recommended, because:
  82 * the browser should generally not depend on any particular component's
  83 existence
  84 * bundling increases the installer's size
  85 * the actual gap between install and receipt of updates should be < 5 minutes
  86 * bundling increases the complexity of the solution
  87
  88 Note that you can always start simple and bundle later, if it becomes required.
  89
  90 ### Implement On-Demand or Just-In-Time Updates (Optional)
  91 Contact the component\_updater OWNERS.