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