Skip to content

Commit fa3d4f0

Browse files
magreenblattmagreenblatt
committed
docs: Add installer.md overview (see #4093)
1 parent 97c56bd commit fa3d4f0

4 files changed

Lines changed: 172 additions & 2 deletions

File tree

‎docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ The Chromium Embedded Framework (CEF) is a simple framework for embedding Chromi
2222
* [Automated Build Setup](automated_build_setup.md) - How to set up an automated build system for CEF.
2323
* [Crash Reporting](crash_reporting.md) - How to handle crash reporting from CEF-based applications.
2424
* [Sandbox Setup](sandbox_setup.md) - Sandbox usage and requirements for CEF.
25+
* [Installer](installer.md) - Support for CEF shared installs on Windows.
2526

2627
The complete list of CEF Wiki pages is available [here](.).
2728

‎docs/installer.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# CEF Installer
2+
3+
**Available starting with CEF version 151.1.**
4+
5+
The CEF Installer Library is part of the standard bootstrap binary and provides
6+
automatic CEF version management for Windows applications using the
7+
[bootstrap architecture](sandbox_setup.md). It downloads, installs, updates, and
8+
uninstalls CEF from a shared installation directory so that multiple applications
9+
can share a single managed copy of a CEF version (including libcef and all
10+
associated DLLs and resources).
11+
12+
Installer behavior is optional. It activates only when a `CEF_INSTALLER_CONFIG`
13+
resource is embedded in the client DLL or bootstrap executable. Without that
14+
resource, the client DLL loads the libcef DLL in the usual way with no installer
15+
involvement.
16+
17+
The authoritative reference is
18+
[libcef_dll/bootstrap/installer/README.md](../libcef_dll/bootstrap/installer/README.md).
19+
This document is a brief overview; follow the links below for full details.
20+
21+
## What It Does
22+
23+
- **Automatic resolution**: On startup, the bootstrap finds the best compatible
24+
CEF version already installed, or downloads and installs one from the CDN.
25+
Downloaded archives are verified against their hash and signed catalog before
26+
installation.
27+
- **Shared installation**: Multiple apps share versioned CEF installations
28+
under a common directory (typically `%LocalAppData%\CEF\` for standard users
29+
or `%ProgramFiles%\CEF\` for admin installs).
30+
- **Updates**: Apps can check for newer CEF versions in the background through
31+
the `RunInstaller` API, or manually via `/cef-update` (when enabled, see below).
32+
- **Uninstall and cleanup**: Removing an app's registration automatically
33+
prunes CEF versions that no other app needs.
34+
- **Version safety**: Revoked versions are excluded, and optional launch-health
35+
tracking rolls back versions that crash repeatedly.
36+
- **Enterprise support**: Group Policy controls can restrict download sources,
37+
enforce offline mirrors, or disable external downloads entirely.
38+
39+
## Quick Start
40+
41+
### 1. Add an installer configuration resource
42+
43+
Embed a `CEF_INSTALLER_CONFIG` JSON resource in your client DLL (or bootstrap
44+
`.exe`):
45+
46+
```json
47+
{
48+
"appid": "A3B9C4D5-E6F7-4A8B-9C0D-E1F2A3B4C5D6",
49+
"vmin": "151.1",
50+
"vmax": "",
51+
"abi_hash": "1234567890ABCDEF",
52+
"launch_health": "explicit"
53+
}
54+
```
55+
56+
Key fields:
57+
58+
| Field | Purpose |
59+
|-------|---------|
60+
| `appid` | Unique UUID for your application (never changes). |
61+
| `vmin` | Minimum compatible CEF version. |
62+
| `vmax` | Maximum compatible CEF version (empty = no upper bound). |
63+
| `abi_hash` | Sandbox compatibility hash from `cef_version.h`. |
64+
| `launch_health` | `"off"`, `"explicit"` (recommended), or `"exit_code"`. |
65+
66+
For the full field reference, see
67+
[Configuration Fields](../libcef_dll/bootstrap/installer/README.md#2-configuration-fields).
68+
69+
### 2. Build with the standard binary distribution (cefclient example)
70+
71+
The standard Windows binary distribution provides an opt-in CMake flag for
72+
building cefclient with installer support:
73+
74+
```bash
75+
cmake -G "Visual Studio 17" -A x64 -DUSE_INSTALLER=On ..
76+
```
77+
78+
This Release-only configuration:
79+
- Builds the bootstrap and sandbox libraries
80+
- Embeds the `CEF_INSTALLER_CONFIG` resource in the client DLL
81+
- Stages only the bootstrap `.exe`, client DLL, and `chrome_elf.dll`
82+
83+
Replace the sample application identity (`appid`) before production use. See
84+
[Build Integration](../libcef_dll/bootstrap/installer/README.md#build-integration)
85+
for resource embedding details.
86+
87+
### 3. Sign your binaries
88+
89+
The bootstrap verifies that `chrome_elf.dll` and the `.exe` share the same
90+
code-signing certificate. Both must be signed before deployment. CEF
91+
installations are signed and verified separately using their own catalog and
92+
certificate.
93+
94+
## Command-Line Usage
95+
96+
Run the bootstrap executable with installer flags:
97+
98+
```
99+
MyApp.exe /cef-update # Check for and install updates
100+
MyApp.exe /cef-update /cef-background # Silent background update
101+
MyApp.exe /cef-uninstall # Unregister and prune unused versions
102+
```
103+
104+
These commands require `enable_explicit_modes: true` in the bootstrap's
105+
embedded configuration. See
106+
[Command-Line Options](../libcef_dll/bootstrap/installer/README.md#command-line-options).
107+
108+
## Background Updates from Code
109+
110+
Client DLLs can trigger updates programmatically via the `RunInstaller` export:
111+
112+
```cpp
113+
auto run_installer = reinterpret_cast<RunInstallerFunc>(
114+
GetProcAddress(GetModuleHandle(nullptr), "RunInstaller"));
115+
const char* result = run_installer("update", config_json.c_str());
116+
```
117+
118+
The result is a JSON string indicating success or failure. Available commands:
119+
`install`, `update`, `uninstall`, `query`, and `launch_success`.
120+
121+
For the full API, result format, and extended configuration options, see
122+
[Background Update API](../libcef_dll/bootstrap/installer/README.md#background-update-api).
123+
124+
## Version Selection
125+
126+
The installer picks the best CEF version from multiple sources:
127+
128+
1. **Installed versions** in the shared directory (or an app-specific
129+
`install_path` if configured)
130+
2. An optional **bundled version** shipped with the app (`bundled_cef_path`)
131+
3. **CDN download** when no local version qualifies
132+
133+
Among qualifying candidates, newer wins; ties go to the installed copy. Revoked
134+
versions are excluded from normal selection, and crash-disqualified versions
135+
(when launch-health tracking is enabled) are deprioritized.
136+
137+
For the complete decision tree, see
138+
[Version Selection](../libcef_dll/bootstrap/installer/README.md#version-selection).
139+
140+
### Bundled CEF Modes
141+
142+
Applications can optionally ship CEF alongside their own binaries instead of
143+
relying solely on the shared installation directory and CDN downloads.
144+
145+
- **`bundled_cef_path`**: Points to a full CEF distribution directory (with
146+
`cef_version.json`, `catalog.cat`, and `Release/libcef.dll`). The bundled
147+
version participates in normal version selection — it is compared against
148+
installed versions and the newer one wins. It is used in-place and never
149+
copied to the shared directory. See
150+
[Bundled Version Behavior](../libcef_dll/bootstrap/installer/README.md#bundled-version-behavior).
151+
152+
- **`unchecked_cef_path`**: Points directly to a directory containing
153+
`libcef.dll`. When set, this path is checked first and bypasses all version,
154+
ABI, signature, and revocation checks — the application is fully responsible
155+
for the integrity of that DLL. If the DLL is absent, the installer falls
156+
through to normal resolution. See
157+
[Unchecked CEF Path](../libcef_dll/bootstrap/installer/README.md#unchecked-cef-path).
158+
159+
## Further Reading
160+
161+
| Topic | Link |
162+
|-------|------|
163+
| Full installer reference | [README.md](../libcef_dll/bootstrap/installer/README.md) |
164+
| Security model | [SECURITY.md](../libcef_dll/bootstrap/installer/SECURITY.md) |
165+
| Enterprise policy | [ADMIN_POLICY.md](../libcef_dll/bootstrap/installer/ADMIN_POLICY.md) |
166+
| Testing | [TESTING.md](../libcef_dll/bootstrap/installer/TESTING.md) |
167+
| Bootstrap/client integration | [sandbox_setup.md](sandbox_setup.md) |

‎docs/sandbox_setup.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ Starting with M138 the `cef_sandbox` static library can only be linked with appl
3939
3. Optionally customize the bootstrap executable for your client application. For example, resources such as icons, file information and error strings can be modified using [Visual Studio](https://learn.microsoft.com/en-us/cpp/windows/working-with-resource-files?view=msvc-170) or [Resource Hacker](https://www.angusj.com/resourcehacker/) tools ([example](https://github.com/chromiumembedded/cef/issues/3824#issuecomment-2895663576)). Alternately, you can build and modify the bootstrap executables from source code as part of a CEF/Chromium build (see the "Building bootstrap" section below).
4040
4. Be sure to [code sign](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool) all binaries after modification and before distribution to users ([example](https://github.com/chromiumembedded/cef/issues/3824#issuecomment-2892139995)).
4141

42+
The bootstrap can also manage CEF downloads, updates, and shared installations automatically. See [Installer](installer.md) for details.
43+
4244
If you don't wish to use the provided bootstrap executables you have a few other options:
4345

4446
1. Build your client application as part of the CEF/Chromium build using Chromium's bundled Clang/LLVM/libc++ toolchain. You will need to integrate your custom build into CEF's top-level [BUILD.gn file](https://github.com/chromiumembedded/cef/blob/master/BUILD.gn). See for example the "cefsimple targets" section in that file for how the cefsimple application is built.

‎tools/distrib/win/README.standard.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,8 +83,8 @@ Building using CMake:
8383
2. Sign cefclient.exe, cefclient.dll, and chrome_elf.dll. chrome_elf.dll must
8484
use the same signing certificate as cefclient.exe.
8585
3. Review the production identity, signing, publication, and installer
86-
requirements in the CEF Installer Library documentation:
87-
https://github.com/chromiumembedded/cef/blob/$CEF_REV$/libcef_dll/bootstrap/installer/README.md
86+
requirements in the CEF Installer documentation:
87+
https://chromiumembedded.github.io/cef/installer.html
8888

8989
This example supports normal first-run CEF resolution. It does not modify
9090
bootstrap.exe resources, so standalone installer mode and explicit commands

0 commit comments

Comments
 (0)