Build dependencies ¶
- x86_64 Linux build environment (macOS is not supported, unlike AOSP which partially supports it)
- Android Open Source Project build dependencies
- Linux kernel build dependencies
- 16GiB of memory or more
- 300GiB of free storage space
Downloading source code ¶
Since this is syncing the sources for the entire operating system and application layer, it will use a lot of bandwidth and storage space.
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.
Development branch ¶
The pie branch is currently used for all supported devices:
mkdir grapheneos-pie cd grapheneos-pie repo init -u https://github.com/GrapheneOS/platform_manifest.git -b pie repo sync -j32
If your network is unreliable and
repo sync fails, you can run the
repo sync command again as many times as needed for it to fully
Stable release ¶
Pick a specific build for a device from the releases page 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.
mkdir grapheneos-TAG_NAME cd grapheneos-TAG_NAME repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/TAG_NAME
Verify the manifest:
gpg --recv-keys 65EEFE022108E2B708CBFCF7F9E712E59AF5F22A gpg --recv-keys 4340D13570EF945E83810964E8AD3F819AB10E78 cd .repo/manifests git verify-tag --raw $(git describe) cd ../..
Complete the source tree download:
repo sync -j32
Verify the source tree:
repo forall -c 'git verify-tag --raw $(git describe)' || echo Verification failed!
These instructions will be extended in the future to check the verify-tag output.
Note that the repo command itself takes care of updating itself and uses gpg to verify by default.
Updating and switching branches or tags ¶
To update the source tree, run the
repo init command again to select
the branch or tag and then run
repo sync -j32 again. You may need to add
--force-sync 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
repo init again to continue down the same branch since
GrapheneOS only provides a stable history via tags.
Browser and WebView ¶Before building GrapheneOS, you need to build Chromium for the WebView and optionally 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
chromium_patchesrepository 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 Chromium's Android build instructions for details on obtaining the prerequisites.
You can obtain the proper configuration from the GrapheneOS chromium_build repository including the correct version.
mkdir chromium cd chromium fetch --nohooks android
Sync to the latest stable release for Android (replace $VERSION with the correct value):
gclient sync -D --with_branch_heads -r $VERSION --jobs 32
Apply the GrapheneOS patches on top of the tagged release:
git clone https://github.com/GrapheneOS/chromium_patches.git cd src git am ../chromium_patches/*.patch
Then, configure the build in the
gn args out/Default
To build Monochrome, which provides both Chromium and the WebView:
ninja -C out/Default/ monochrome_public_apk
The apk needs to be copied from
into the Android source tree at
Standalone builds of Chromium and the WebView can be done via the
system_webview_apk 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
The kernel needs to be built in advance, since it uses a separate build system.
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
For example, to build the kernel for blueline:
cd kernel/google/crosshatch git submodule sync git submodule update --init ./build.sh blueline
kernel/google/marlin repository is for the Pixel and Pixel XL, the
kernel/google/wahoo repository is for the Pixel 2 and Pixel 2 XL and the
kernel/google/crosshatch repository is for the Pixel 3 and Pixel 3
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.
Setting up the OS build environment ¶
The build has to be done from bash as envsetup.sh is not compatible with other shells like zsh.
Set up the build environment:
Select the desired build target (
aosp_crosshatch is the Pixel 3 XL):
choosecombo release aosp_crosshatch user
For a development build, you may want to replace
userdebug in order to have better debugging support. Production builds
user builds as they are significantly more secure and don't
make additional performance sacrifices to improve debugging.
Reproducible builds ¶
To reproduce a past build, you need to export
BUILD_NUMBER to the values set for the past build. These can be obtained
out/build_number.txt in a build
output directory and the
ro.build.version.incremental properties which are also included in the
over-the-air zip metadata rather than just the OS itself.
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.
Extracting vendor files for Pixel devices ¶
This section does not apply to devices where no extra vendor files are required (HiKey, HiKey 960, emulator, generic targets).
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).
Extract the vendor files corresponding to the matching release:
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/
Note that android-prepare-vendor is non-deterministic unless a timestamp parameter is
--timestamp (seconds since Epoch).
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:
rm -r out
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:
make target-files-package -j20
Faster builds for development use only ¶
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:
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.
Generating release signing keys ¶
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.
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.
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.
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
Android Verified Boot 1.0 ¶
To generate keys for marlin (you should use unique keys per device variant):
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 ../..
Generate the verity public key:
make -j20 generate_verity_key out/host/linux-x86/bin/generate_verity_key -convert keys/marlin/verity.x509.pem keys/marlin/verity_key
Generate verity keys in the format used by the kernel for the Pixel and Pixel XL:
openssl x509 -outform der -in keys/marlin/verity.x509.pem -out kernel/google/marlin/verifiedboot_marlin_relkeys.der.x509
The same kernel and device repository is used for the Pixel and Pixel XL. There's no separate sailfish kernel.
Android Verified Boot 2.0 (AVB) ¶
To generate keys for crosshatch (you should use unique keys per device variant):
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 ../..
avb_pkmd.bin file isn't needed for generating a signed release but
rather to set the public key used by the device to enforce verified boot.
Generating signed factory images and full update packages ¶
Build the tool needed to generate A/B updates:
make -j20 brillo_update_payload
Generate a signed release build with the release.sh script:
The factory images and update package will be in
out/release-crosshatch-$BUILD_NUMBER. 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
target_files zips and generating
incremental updates from those to the most recent signed
Prebuilt code ¶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.
Prebuilt apps ¶
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.