1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
|
<!DOCTYPE html>
<html lang="en" prefix="og: http://ogp.me/ns#">
<head>
<meta charset="utf-8"/>
<title>Build | GrapheneOS</title>
<meta name="description" content="Building instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
<meta name="theme-color" content="#212121"/>
<meta name="msapplication-TileColor" content="#ffffff"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="twitter:site" content="@GrapheneOS"/>
<meta name="twitter:creator" content="@GrapheneOS"/>
<meta property="og:title" content="GrapheneOS build documentation"/>
<meta property="og:description" content="Building instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
<meta property="og:type" content="website"/>
<meta property="og:image" content="https://grapheneos.org/opengraph.png"/>
<meta property="og:image:width" content="512"/>
<meta property="og:image:height" content="512"/>
<meta property="og:image:alt" content="GrapheneOS logo"/>
<meta property="og:url" content="https://grapheneos.org/build"/>
<meta property="og:site_name" content="GrapheneOS"/>
<link rel="icon" type="image/vnd.microsoft.icon" href="/favicon.ico"/>
<link rel="mask-icon" href="/safari_pinned_tab_icon.svg" color="#000000"/>
<link rel="stylesheet" href="/grapheneos.css?9"/>
<link rel="manifest" href="/manifest.webmanifest"/>
<link rel="canonical" href="https://grapheneos.org/build"/>
</head>
<body>
<nav>
<ul>
<li><a href="/">GrapheneOS</a></li>
<li><a href="/install">Install</a></li>
<li class="active"><a href="/build">Build</a></li>
<li><a href="/usage">Usage</a></li>
<li><a href="/releases">Releases</a></li>
<li><a href="/source">Source</a></li>
<li><a href="/donate">Donate</a></li>
<li><a href="/contact">Contact</a></li>
</ul>
</nav>
<div id="content">
<h1 id="build">
<a href="#build">Build</a>
</h1>
<h2 id="build-dependencies">
<a href="#build-dependencies">Build dependencies</a>
</h2>
<ul>
<li>x86_64 Linux build environment (macOS is not supported, unlike AOSP which
partially supports it)</li>
<li>Android Open Source Project build dependencies</li>
<li>Linux kernel build dependencies</li>
<li>16GiB of memory or more</li>
<li>300GiB of free storage space</li>
</ul>
<h2 id="downloading-source-code">
<a href="#downloading-source-code">Downloading source code</a>
</h2>
<p>Since this is syncing the sources for the entire operating system and application
layer, it will use a lot of bandwidth and storage space.</p>
<p>You likely want to use the most recent stable tag, not the development branch, even
for developing a feature. It's easier to port between stable tags that are known to
work properly than dealing with a moving target.</p>
<h2 id="development-branch">
<a href="#development-branch">Development branch</a>
</h2>
<p>The pie branch is currently used for all supported devices:</p>
<pre>mkdir grapheneos-pie
cd grapheneos-pie
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b pie
repo sync -j32</pre>
<p>If your network is unreliable and <code>repo sync</code> fails, you can run the
<code>repo sync</code> command again as many times as needed for it to fully
succeed.</p>
<h2 id="stable-release">
<a href="#stable-release">Stable release</a>
</h2>
<p>Pick a specific build for a device from the <a href="/releases">releases page</a>
and download the source tree. Note that some devices use different Android Open Source
Project branches so they can end up with different tags. Make sure to use the correct
tag for a device. For devices without official support, use the latest tag for the
Pixel 3.</p>
<pre>mkdir grapheneos-TAG_NAME
cd grapheneos-TAG_NAME
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/TAG_NAME</pre>
<p>Verify the manifest:</p>
<pre>gpg --recv-keys 65EEFE022108E2B708CBFCF7F9E712E59AF5F22A
gpg --recv-keys 4340D13570EF945E83810964E8AD3F819AB10E78
cd .repo/manifests
git verify-tag --raw $(git describe)
cd ../..</pre>
<p>Complete the source tree download:</p>
<pre>repo sync -j32</pre>
<p>Verify the source tree:</p>
<pre>repo forall -c 'git verify-tag --raw $(git describe)' || echo Verification failed!</pre>
<p>These instructions will be extended in the future to check the verify-tag
output.</p>
<p>Note that the repo command itself takes care of updating itself and uses gpg to
verify by default.</p>
<h2 id="updating-and-switching-branches-or-tags">
<a href="#updating-and-switching-branches-or-tags">Updating and switching branches or tags</a>
</h2>
<p>To update the source tree, run the <code>repo init</code> command again to select
the branch or tag and then run <code>repo sync -j32</code> again. You may need to add
<code>--force-sync</code> if a repository from switched from one source to another,
such as when GrapheneOS forks an additional Android Open Source Project repository.
You don't need to start over to switch between different branches or tags. You may
need to run <code>repo init</code> again to continue down the same branch since
GrapheneOS only provides a stable history via tags.</p>
<h2 id="browser-and-webview">
<a href="#browser-and-webview">Browser and WebView</a>
</h2>
Before building GrapheneOS, you need to build Chromium for the WebView and
<em>optionally</em> the standalone browser app. GrapheneOS uses a hardened fork of
Chromium for these. It needs to be rebuilt when Chromium is updated or the GrapheneOS
<code>chromium_patches</code> repository changes.
Chromium and the WebView are independent applications built from the Chromium source tree. The
GrapheneOS Chromium build is located at external/chromium and includes the WebView.
See <a href="https://www.chromium.org/developers/how-tos/android-build-instructions">
Chromium's Android build instructions</a> for details on obtaining the prerequisites.
<p>You can obtain the proper configuration from the
<a href="https://github.com/GrapheneOS/chromium_build">
GrapheneOS chromium_build repository</a> including the correct version.</p>
<pre>mkdir chromium
cd chromium
fetch --nohooks android</pre>
<p>Sync to the latest stable release for Android (replace $VERSION with the correct
value):</p>
<pre>gclient sync -D --with_branch_heads -r $VERSION --jobs 32</pre>
<p>Apply the GrapheneOS patches on top of the tagged release:</p>
<pre>git clone https://github.com/GrapheneOS/chromium_patches.git
cd src
git am ../chromium_patches/*.patch</pre>
<p>Then, configure the build in the <code>src</code> directory:</p>
<pre>gn args out/Default</pre>
<p>To build Monochrome, which provides both Chromium and the WebView:</p>
<pre>ninja -C out/Default/ monochrome_public_apk</pre>
<p>The apk needs to be copied from <code>out/Default/apks/MonochromePublic.apk</code>
into the Android source tree at
<code>external/chromium/prebuilt/arm64/MonochromePublic.apk</code></p>
<p>Standalone builds of Chromium and the WebView can be done via the
<code>chrome_modern_public_apk</code> and <code>system_webview_apk</code> targets but
those aren't used by GrapheneOS. The build system isn't set up for including them and
the standalone WebView isn't whitelisted in
<code>frameworks/base/core/res/res/xml/config_webview_packages</code>.</p>
<h2 id="kernel">
<a href="#kernel">Kernel</a>
</h2>
<p>The kernel needs to be built in advance, since it uses a separate build system.</p>
<p>For the Pixel 3 and Pixel 3 XL, the kernel repository uses submodules for building
in out-of-tree modules. You need to make sure the submodule sources are updated before
building. In the future, this should end up being handled automatically by
<code>repo</code>.</p>
<p>For example, to build the kernel for blueline:</p>
<pre>cd kernel/google/crosshatch
git submodule sync
git submodule update --init
./build.sh blueline</pre>
<p>The <code>kernel/google/marlin</code> repository is for the Pixel and Pixel XL, the
<code>kernel/google/wahoo</code> repository is for the Pixel 2 and Pixel 2 XL and the
<code>kernel/google/crosshatch</code> repository is for the Pixel 3 and Pixel 3
XL.</p>
<p><em>For the first generation Pixel (sailfish) and Pixel XL (marlin), signed
releases require building the verity public key into the kernel so the keys need to be
generated per the instructions below before building the kernel.</em></p>
<h2 id="setting-up-the-os-build-environment">
<a href="#setting-up-the-os-build-environment">Setting up the OS build environment</a>
</h2>
<p>The build has to be done from bash as envsetup.sh is not compatible with other
shells like zsh.</p>
<p>Set up the build environment:</p>
<pre>source script/envsetup.sh</pre>
<p>Select the desired build target (<code>aosp_crosshatch</code> is the Pixel 3 XL):
<pre>choosecombo release aosp_crosshatch user</pre>
<p>For a development build, you may want to replace <code>user</code> with
<code>userdebug</code> in order to have better debugging support. Production builds
should be <code>user</code> builds as they are significantly more secure and don't
make additional performance sacrifices to improve debugging.</p>
<h2 id="reproducible-builds">
<a href="#reproducible-builds">Reproducible builds</a>
</h2>
<p>To reproduce a past build, you need to export <code>BUILD_DATETIME</code> and
<code>BUILD_NUMBER</code> to the values set for the past build. These can be obtained
from <code>out/build_date.txt</code> and <code>out/build_number.txt</code> in a build
output directory and the <code>ro.build.date.utc</code> and
<code>ro.build.version.incremental</code> properties which are also included in the
over-the-air zip metadata rather than just the OS itself.</p>
<p>The signing process for release builds is done after completing builds and replaces
the dm-verity trees, apk signatures, etc. and can only be reproduced with access to
the same private keys. If you want to compare to production builds signed with
different keys you need to stick to comparing everything other than the
signatures.</p>
<h2 id="extracting-vendor-files-for-pixel-devices">
<a href="#extracting-vendor-files-for-pixel-devices">Extracting vendor files for Pixel devices</a>
</h2>
<p>This section does not apply to devices where no extra vendor files are required (HiKey, HiKey 960, emulator, generic targets).</p>
<p>Many of these components are already open source, but not everything is set up to
be built by the Android Open Source Project build system. Switching to building these
components from source will be an incremental effort. In many cases, the vendor files
simply need to be ignored and AOSP will already provide them instead. Firmware cannot
generally be built from source even when sources are available, other than to verify
that the official builds match the sources, since it has signature verification (which
is an important part of the verified boot and attestation security model).</p>
<p>Extract the vendor files corresponding to the matching release:</p>
<pre>vendor/android-prepare-vendor/execute-all.sh -d DEVICE -b BUILD_ID -o vendor/android-prepare-vendor
mkdir -p vendor/google_devices
rm -rf vendor/google_devices/DEVICE
mv vendor/android-prepare-vendor/DEVICE/BUILD_ID/vendor/google_devices/* vendor/google_devices/</pre>
<p>Note that android-prepare-vendor is non-deterministic unless a timestamp parameter is
passed with <code>--timestamp</code> (seconds since Epoch).</p>
<h2 id="building">
<a href="#building">Building</a>
</h2>
<p>Incremental builds (i.e. starting from the old build) usually work for development
and are the normal way to develop changes. However, there are cases where changes are
not properly picked up by the build system. For production builds, you should remove
the remnants of any past builds before starting, particularly if there were
non-trivial changes:</p>
<pre>rm -r out</pre>
<p>Start the build process, with -j# used to set the number of parallel jobs to the
number of CPU threads. You also need 2-4GiB of memory per job, so reduce it based on
available memory if necessary:</p>
<pre>make target-files-package -j20</pre>
<h2 id="faster-builds-for-development-use-only">
<a href="#faster-builds-for-development-use-only">Faster builds for development use only</a>
</h2>
<p>The normal production build process involves building a target files package to be
resigned with secure release keys and then converted into factory images and/or an
update zip via the sections below. If you have a dedicated development device with no
security requirements, you can save time by using the default make target, leaving the
bootloader unlocked and flashing the raw images that are signed with the default
public test keys:</p>
<pre>make -j20</pre>
<p>Technically, you could generate test key signed update packages. However, there's
no point of sideloading update packages when the bootloader is unlocked and there's no
value in a locked bootloader without signing the build using release keys, since
verified boot will be meaningless and the keys used to verify sideloaded updates are
also public. The only reason to use update packages or a locked bootloader without
signing the build with release keys would be testing that functionality and it makes a
lot more sense to test it with proper signing keys rather than the default public test
keys.</p>
<h2 id="generating-release-signing-keys">
<a href="#generating-release-signing-keys">Generating release signing keys</a>
</h2>
<p>Keys need to be generated for resigning completed builds from the publicly
available test keys. The keys must then be reused for subsequent builds and cannot be
changed without flashing the generated factory images again which will perform a
factory reset. Note that the keys are used for a lot more than simply verifying
updates and verified boot.</p>
<p>The keys should not be given passwords due to limitations in the upstream scripts.
If you want to secure them at rest, you should take a different approach where they
can still be available to the signing scripts as a directory of unencrypted keys. The
sample certificate subject can be replaced with your own information or simply left
as-is.</p>
<p>The Pixel and Pixel XL use Android Verified Boot 1.0. The Pixel 2, Pixel 2 XL,
Pixel 3 and Pixel 3 XL use Android Verified Boot 2.0 (AVB). Follow the appropriate
instructions below.</p>
<p><em>For the first generation Pixel (sailfish) and Pixel XL (marlin), signed
releases require building the verity public key into the kernel, so this needs to be
done before building the kernel</em></p>
<h3 id="android-verified-boot-1.0">
<a href="#android-verified-boot-1.0">Android Verified Boot 1.0</a>
</h3>
<p>To generate keys for marlin (you should use unique keys per device variant):</p>
<pre>mkdir -p keys/marlin
cd keys/marlin
../../development/tools/make_key releasekey '/CN=GrapheneOS/'
../../development/tools/make_key platform '/CN=GrapheneOS/'
../../development/tools/make_key shared '/CN=GrapheneOS/'
../../development/tools/make_key media '/CN=GrapheneOS/'
../../development/tools/make_key verity '/CN=GrapheneOS/'
cd ../..</pre>
<p>Generate the verity public key:</p>
<pre>make -j20 generate_verity_key
out/host/linux-x86/bin/generate_verity_key -convert keys/marlin/verity.x509.pem keys/marlin/verity_key</pre>
<p>Generate verity keys in the format used by the kernel for the Pixel and Pixel XL:</p>
<pre>openssl x509 -outform der -in keys/marlin/verity.x509.pem -out kernel/google/marlin/verifiedboot_marlin_relkeys.der.x509</pre>
<p>The same kernel and device repository is used for the Pixel and Pixel XL. There's
no separate sailfish kernel.</p>
<h3 id="android-verified-boot-2.0">
<a href="#android-verified-boot-2.0">Android Verified Boot 2.0 (AVB)</a>
</h3>
<p>To generate keys for crosshatch (you should use unique keys per device
variant):</p>
<pre>mkdir -p keys/crosshatch
cd keys/crosshatch
../../development/tools/make_key releasekey '/CN=GrapheneOS/'
../../development/tools/make_key platform '/CN=GrapheneOS/'
../../development/tools/make_key shared '/CN=GrapheneOS/'
../../development/tools/make_key media '/CN=GrapheneOS/'
openssl genrsa -out avb.pem 2048
../../external/avb/avbtool extract_public_key --key avb.pem --output avb_pkmd.bin
cd ../..</pre>
<p>The <code>avb_pkmd.bin</code> file isn't needed for generating a signed release but
rather to set the public key used by the device to enforce verified boot.</p>
<h2 id="generating-signed-factory-images-and-full-update-packages">
<a href="#generating-signed-factory-images-and-full-update-packages">Generating signed factory images and full update packages</a>
</h2>
<p>Build the tool needed to generate A/B updates:</p>
<pre>make -j20 brillo_update_payload</pre>
<p>Generate a signed release build with the release.sh script:</p>
<pre>script/release.sh crosshatch</pre>
<p>The factory images and update package will be in
<code>out/release-crosshatch-$BUILD_NUMBER</code>. The update zip performs a full OS
installation so it can be used to update from any previous version. More efficient
incremental updates are used for official over-the-air GrapheneOS updates and can be
generated by keeping around past signed <code>target_files</code> zips and generating
incremental updates from those to the most recent signed <code>target_files</code>
zip.</p>
<h2 id="prebuilt-code">
<a href="#prebuilt-code">Prebuilt code</a>
</h2>
Like the Android Open Source Project, GrapheneOS contains some code that's built
separately and then bundled into the source tree as binaries. This section will be
gradually expanded to cover building all of it.
<h3 id="prebuilt-apps">
<a href="#prebuilt-apps">Prebuilt apps</a>
</h3>
<p>The Auditor app is simply built from the latest upstream tag and bundled as an apk into
external/ repositories. There are no modifications to it for GrapheneOS.</p>
<h2 id="testing">
<a href="#testing">Testing</a>
</h2>
<h3 id="compatibility-test-suite">
<a href="#compatibility-test-suite">Compatibility Test Suite</a>
</h3>
<h4 id="compatibility-test-suite-download">
<a href="#compatibility-test-suite-download">Download</a>
</h4>
<p>Testing with the Compatibility Test Suite (CTS) can be done by either building the
test suite from source or using the official releases.</p>
<p>Official releases of the CTS can be downloaded from
<a href="https://source.android.com/compatibility/cts/downloads">the Compatibility
Suite Downloads page</a>. You should download the CTS for the relevant release
(Android 9) and architecture (ARM). There's a separate zip for the main CTS, the
manual portion (CTS Verifier) and the CTS for Instant Apps. The latest release of the
CTS Media Files also needs to be downloaded from that section.</p>
<h4 id="compatibility-test-suite-setup">
<a href="#compatibility-test-suite-setup">Setup</a>
</h4>
<p>You'll need a device attached to your computer with ADB enabled along with the
Android SDK installed. The build-tools and platform-tools packages need to be
installed and the binaries need to be added to your PATH. For example, with the SDK
located at <code>/home/username</code>:</p>
<pre>export ANDROID_HOME="$HOME/sdk"
export PATH="$PATH:$HOME/sdk/tools:$HOME/sdk/tools/bin:$HOME/sdk/platform-tools:$HOME/sdk/build-tools/27.0.3:$HOME/sdk/ndk-bundle"</pre>
<p>Copy media onto the device:</p>
<pre>cd android-cts-media-1.4
./copy_images.sh
./copy_media.sh</pre>
<p>You also need to do some basic setup for the device. It's possible for changes from
a baseline install to cause interference, so it can be a good idea to factory reset
the device if assorted changes have been made. The device needs to be running a user
build for the security model to be fully intact in order to pass all the security
tests. A userdebug build is expected to fail some of the tests. GrapheneOS also makes
various changes intentionally deviating from the requirements expected by the CTS, so
there will always be some expected failures. A few of the tests are also known to be
quite flaky or broken even with the stock OS and/or AOSP. These will be documented
here at some point.</p>
<ul>
<li>Must be connected to a WiFi network with IPv6 internet access</li>
<li>Must have a working SIM card with mobile data with IPv6 internet access</li>
<li>Disable SIM lock</li>
<li>Enable Bluetooth</li>
<li>Enable NFC and NDEF (Android Beam)</li>
<li>Open / close Chromium to deal with initial setup</li>
<li>Prop up with a good object to focus on and good lighting for Camera tests</li>
<li>Bluetooth beacons for Bluetooth tests</li>
<li>Must have a great GPS/GNSS signal for location tests</li>
<li>SIM card with carrier privilege rules</li>
<li>Secure element applet installed on the embedded secure element or SIM
card</li>
<li>At least one Wi-Fi RTT access point powered up but not connected to any
network</li>
</ul>
<h4 id="compatibility-test-suite-run-modules">
<a href="#compatibility-test-suite-run-modules">Run modules</a>
</h4>
<p>Run the test harness:</p>
<pre>./android-cts/tools/cts-tradefed</pre>
<p>Note that <code>_JAVA_OPTIONS</code> being set will break the version detection.</p>
<p>To obtain a list of CTS modules:</p>
<pre>list modules</pre>
<p>To run a specific module and avoid wasting time capturing device information:</p>
<pre>run cts --skip-device-info --module CtsModuleName</pre>
<p>To speed up initialization after running some initial tests:</p>
<pre>run cts --skip-device-info --skip-preconditions --module CtsModuleName</pre>
<p>It's possible to run the whole standard CTS plan with a single command, but running
specific modules is recommended, especially if you don't have everything set up for
the entire test suite.</p>
</div>
<footer>
<a href="/"><img src="https://grapheneos.org/logo.png" width="512" height="512" alt=""/>GrapheneOS</a>
<div id="social">
<a href="https://twitter.com/GrapheneOS">Twitter</a>
<a href="https://github.com/GrapheneOS">GitHub</a>
</div>
</footer>
</body>
</html>
|
