Building GrapheneOS
Build targets
Smartphone targets:
- cheetah (Pixel 7 Pro)
- panther (Pixel 7)
- bluejay (Pixel 6a)
- raven (Pixel 6 Pro)
- oriole (Pixel 6)
- barbet (Pixel 5a)
- redfin (Pixel 5)
- bramble (Pixel 4a (5G))
- sunfish (Pixel 4a)
- coral (Pixel 4 XL) (extended support)
- flame (Pixel 4) (extended support)
These are all fully supported production-ready targets supporting all the baseline security features and receiving full monthly security updates covering all firmware, kernel drivers, driver libraries / services and other device-specific code. A fully signed user build for these devices is a proper GrapheneOS release. Newer generation devices have stronger hardware / firmware security and hardware-based OS security features and are better development devices for that reason. It's not possible to work on everything via past generation devices. The best development devices are the Pixel 6 and 7 series.
SDK emulator targets:
- sdk_phone_armv7
- sdk_phone_arm64
- sdk_phone_x86
- sdk_phone_x86_64
These are extended versions of the generic targets with extra components for the SDK. These targets don't receive full monthly security updates, don't provide all of the baseline security features and are intended for development usage.
We recommend using the sdk_phone_x86_64 target in either the userdebug or eng variant for most development work.
Generic targets:
- aosp_arm
- aosp_arm64
- aosp_x86
- aosp_x86_64
These generic targets can be used with the emulator along with many smartphones, tablets and other devices. These targets don't receive full monthly security updates, don't offer all of the baseline security features and are intended for development usage.
Providing proper support for a device or generic device family requires providing an up-to-date kernel and device support code including driver libraries, firmware and device SELinux policy extensions. Other than some special cases like the emulator, the generic targets rely on the device support code present on the device. Shipping all of this is necessary for full security updates and is tied to enabling verified boot / attestation. Pixel targets have a lot of device-specific hardening in the AOSP base along with some in GrapheneOS which needs to be ported over too. For example, various security features in the kernel including type-based Control Flow Integrity (CFI) and the shadow call stack are currently specific to the kernels for these devices.
Build dependencies
Arch Linux, Debian bullseye and Ubuntu 22.04 LTS are the officially supported operating systems for building GrapheneOS.
Dependencies for fetching and verifying the sources:
- repo
- python3 (for repo)
- git (both for repo and manual usage)
- gnupg (both for repo and manual usage)
- 131GiB+ storage for a standard sync with history, 61GiB+ storage for a lightweight sync
Baseline build dependencies:
- x86_64 Linux build environment
- Android Open Source Project build dependencies
- 16GiB of memory or more. Link-Time Optimization (LTO) creates huge peaks during linking and is mandatory for Control Flow Integrity (CFI). Linking Vanadium (Chromium) and the Linux kernel with LTO + CFI are the most memory demanding tasks.
- 100GiB+ of additional free storage space for a typical build of the entire OS for a multiarch device
- en_US.UTF-8 locale supported
You can either obtain repo
as a distribution package or the self-updating standalone version from the Android Open Source Project. The self-updating variant avoids dealing with out-of-date distribution packages and depends on GPG to verify updates.
The Android Open Source Project build system is designed to provide reliable and reproducible builds. To accomplish this, it provides a prebuilt toolchain and other utilities fulfilling most of the build dependency requirements itself. These prebuilt tools have reproducible builds themselves. It runs the build process within a loose sandbox to avoid accidental dependencies on the host system. The process of moving to a fully self-contained build process with minimal external dependencies is gradual and there are still dependencies that need to be installed on the host system.
The Linux kernel build process is not integrated into the rest of the AOSP build process, but does reuse the same prebuilts to make the build reproducible.
Additional Linux kernel build dependencies not provided by the source tree:
- libgcc (for the host, not the target)
- binutils (for the host, not the target)
The dependency on the host libgcc and binutils for building utilities during the build process will be phased out by moving to a pure LLVM-based toolchain alongside doing it for the target. This is lagging a bit behind for the kernel, particularly code built for the host.
Additional Android Open Source Project build dependencies not provided by the source tree:
- diff (diffutils)
- freetype2 and any OpenType/TrueType font (such as DejaVu but anything works) for OpenJDK despite it being a headless variant without GUI support
- ncurses5 (provided by the source tree for some tools but not others)
- openssl
- rsync
- unzip
- zip
Additional dependencies for extracting vendor files with adevtool:
- protobuf library for Python 3
- node 17 or later
- yarn
Additional Vanadium (Chromium) build dependencies not provided by the source tree:
- gperf
- 32-bit glibc
- 32-bit gcc runtime library
The signify
tool (with the proper naming) is also required for signing factory images zips.
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 13
branch is the main development branch of GrapheneOS. It follows along with the latest stable releases of the Android Open Source Project which currently means the latest monthly release of the android13-release
(Android 13) branch. The 13
branch of GrapheneOS should be used for generic builds including the emulator, porting to other devices and for non-legacy officially supported devices.
The 13
branch is used for 4th, 5th, 6th and 7th generation Pixels, generic / emulator targets and non-Pixel devices:
mkdir grapheneos-13 cd grapheneos-13 repo init -u https://github.com/GrapheneOS/platform_manifest.git -b 13 repo sync -j16
If your network is unreliable and repo sync
fails, you can run the repo sync
command again to continue from where it was interrupted. It handles connection failures robustly and you shouldn't start over from scratch.
Stable release
Pick a specific release 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 marked as being appropriate for generic / other devices in the release notes.
mkdir grapheneos-TAG_NAME cd grapheneos-TAG_NAME repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/TAG_NAME
Obtain SSH public key for verifying tags:
curl https://grapheneos.org/allowed_signers > ~/.ssh/grapheneos_allowed_signers
Verify the manifest:
cd .repo/manifests git config gpg.ssh.allowedSignersFile ~/.ssh/grapheneos_allowed_signers git verify-tag $(git describe) cd ../..
Complete the source tree download:
repo sync -j16
The manifest for the latest stable release refers to the revisions in other repositories via commit hashes rather than tag names. This avoids the need to use a script to verify tag signatures across all the repositories, since they simply point to the same commits with the same hashes.
Note that the repo command itself takes care of updating itself and uses GPG to verify by default.
Kernel
The kernel needs to be built in advance, since it uses a separate build system.
Prebuilts are provided for all the officially supported devices, so this step is optional.
4th generation Pixels
mkdir -p android/kernel/coral cd android/kernel/coral repo init -u https://github.com/GrapheneOS/kernel_manifest-coral.git -b 13 repo sync -j16
To build the coral kernel for the Pixel 4 and Pixel 4 XL:
KBUILD_BUILD_VERSION=1 KBUILD_BUILD_USER=build-user KBUILD_BUILD_HOST=build-host KBUILD_BUILD_TIMESTAMP="Thu 01 Jan 1970 12:00:00 AM UTC" BUILD_CONFIG=private/msm-google/build.config.floral build/build.sh
To build the sunfish kernel for the Pixel 4a:
KBUILD_BUILD_VERSION=1 KBUILD_BUILD_USER=build-user KBUILD_BUILD_HOST=build-host KBUILD_BUILD_TIMESTAMP="Thu 01 Jan 1970 12:00:00 AM UTC" BUILD_CONFIG=private/msm-google/build.config.sunfish build/build.sh
Replace the files in the OS source tree at device/google/coral-kernel/
or device/google/sunfish-kernel/
with your build in out/android-msm-pixel-4.14/dist/
.
5th generation Pixels
For 5th generation Pixels:
mkdir -p android/kernel/redbull cd android/kernel/redbull repo init -u https://github.com/GrapheneOS/kernel_manifest-redbull.git -b 13 repo sync -j16
To build the redbull kernel for the Pixel 4a (5G), Pixel 5 and Pixel 5a kernel:
BUILD_CONFIG=private/msm-google/build.config.redbull.vintf build/build.sh
Replace the files in the OS source tree at device/google/redbull-kernel/
(userdebug/eng) and device/google/redbull-kernel/vintf/
(user) with your build in out/android-msm-pixel-4.19/dist/
.
6th generation Pixels
To sync the raviole kernel for the Pixel 6 and Pixel 6 Pro:
mkdir -p android/kernel/raviole cd android/kernel/raviole repo init -u https://github.com/GrapheneOS/kernel_manifest-raviole.git -b 13 repo sync -j16
To sync the bluejay kernel for the Pixel 6a:
mkdir -p android/kernel/bluejay cd android/kernel/bluejay repo init -u https://github.com/GrapheneOS/kernel_manifest-bluejay.git -b 13 repo sync -j16
To build the raviole kernel for the Pixel 6 and Pixel 6 Pro:
LTO=full BUILD_KERNEL=1 ./build_slider.sh
To build the bluejay kernel for the Pixel 6a:
LTO=full BUILD_KERNEL=1 ./build_bluejay.sh
Replace the files in the OS source tree at device/google/raviole-kernel/
or device/google/bluejay-kernel/
with your build in out/mixed/dist/
.
7th generation Pixels
To sync the pantah kernel for the Pixel 7 and Pixel 7 Pro:
mkdir -p android/kernel/pantah cd android/kernel/pantah repo init -u https://github.com/GrapheneOS/kernel_manifest-pantah.git -b 13 repo sync -j16
To build the pantah kernel for the Pixel 7 and Pixel 7 Pro:
LTO=full BUILD_AOSP_KERNEL=1 ./build_cloudripper.sh
Replace the files in the OS source tree at device/google/pantah-kernel/
with your build in out/mixed/dist/
.
Extracting vendor files for Pixel devices
This section is specific to Pixel devices. The emulator and generic targets don't require extra vendor files.
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).
The below commands need to only be run once to initially create a working environment.
yarn install --cwd vendor/adevtool/ source script/envsetup.sh m aapt2
Extract the vendor files corresponding to the matching release with DEVICE
and BUILD_ID
replaced with the appropriate values:
vendor/adevtool/bin/run download vendor/adevtool/dl/ -d DEVICE -b BUILD_ID -t factory ota sudo vendor/adevtool/bin/run generate-all vendor/adevtool/config/DEVICE.yml -c vendor/state/DEVICE.json -s vendor/adevtool/dl/DEVICE-BUILD_ID-*.zip sudo chown -R $(logname):$(logname) vendor/{google_devices,adevtool} vendor/adevtool/bin/run ota-firmware vendor/adevtool/config/DEVICE.yml -f vendor/adevtool/dl/DEVICE-ota-BUILD_ID-*.zip
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:
source script/envsetup.sh
Select the desired build target (raven
is the Pixel 6 Pro):
choosecombo release raven user
For a development build, you may want to replace user
with userdebug
in order to have better debugging support. Production builds should be user
builds as they are significantly more secure and don't make additional performance sacrifices to improve debugging.
Set OFFICIAL_BUILD=true
to include the Updater app. You must change the URL in packages/apps/Updater/res/values/config.xml
to your own update server URL. Using the official update server with a build signed with different keys will not work and will essentially perform a denial of service attack on our update service. If you try to use the official URL, the app will download an official update and will detect it as corrupted or tampered. It will delete the update and try to download it over and over again since it will never be signed with your key.
export OFFICIAL_BUILD=true
Reproducible builds
To reproduce a past build, you need to export BUILD_DATETIME
and BUILD_NUMBER
to the values set for the past build. These can be obtained from out/build_date.txt
and out/build_number.txt
in a build output directory and the ro.build.date.utc
and 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.
Additionally, set OFFICIAL_BUILD=true
per the instructions above to reproduce the official builds. Note that if you do not change the URL to your own domain, you must disable the Updater app before connecting the device to the internet, or you will be performing a denial of service attack on our official update server.
Building
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
Next, start the build process with the m
command:
m target-files-package
For the Pixel 6, Pixel 6 Pro and Pixel 6a you currently need m vendorbootimage target-files-package
instead of target-files-package
.
For the Pixel 7 and Pixel 7 Pro you currently need m vendorbootimage vendorkernelbootimage target-files-package
instead of target-files-package
.
The -j
parameter can be passed to m
to set a specific number of jobs such as -j4
to use 4 jobs. By default, the build system sets the number of jobs to NumCPU() + 2
where NumCPU()
is the number of available logical CPUs.
For an emulator build, always use the development build approach below.
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 build target rather than target-files-package. Leave the bootloader unlocked and flashing the raw images that are signed with the default public test keys.
To build the default build target:
m
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 sample certificate subject (CN=GrapheneOS
) should be replaced with your own information.
You should set a passphrase for the signing keys to keep them at rest until you need to sign a release with them. The GrapheneOS scripts (make_key
and encrypt_keys.sh
) encrypt the signing keys using scrypt for key derivation and AES256 as the cipher. If you use swap, make sure it's encrypted, ideally with an ephemeral key rather a persistent key to support hibernation. Even with an ephemeral key, swap will reduce the security gained from encrypting the keys since it breaks the guarantee that they become at rest as soon as the signing process is finished. Consider disabling swap, at least during the signing process.
The encryption passphrase for all the keys generated for a device needs to match for compatibility with the GrapheneOS scripts.
To generate keys for raven (you should use unique keys per device variant):
mkdir -p keys/raven cd keys/raven CN=GrapheneOS ../../development/tools/make_key releasekey "/CN=$CN/" ../../development/tools/make_key platform "/CN=$CN/" ../../development/tools/make_key shared "/CN=$CN/" ../../development/tools/make_key media "/CN=$CN/" ../../development/tools/make_key networkstack "/CN=$CN/" ../../development/tools/make_key sdk_sandbox "/CN=$CN/" ../../development/tools/make_key bluetooth "/CN=$CN/" openssl genrsa 4096 | openssl pkcs8 -topk8 -scrypt -out avb.pem ../../external/avb/avbtool extract_public_key --key avb.pem --output avb_pkmd.bin cd ../..
The 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.
Generate a signify key for signing factory images:
signify -G -n -p keys/raven/factory.pub -s keys/raven/factory.sec
Remove the -n
switch to set a passphrase. The signify
tool doesn't provide a way to change the passphrase without generating a new key, so this is currently handled separately from encrypting the other keys and there will be a separate prompt for the passphrase. In the future, expect this to be handled by the same scripts along with the expectation of it using the same passphrase as the other keys.
Migration to Android 13
You need to generate a key for sdk_sandbox
and bluetooth
if you generated your keys for a previous release.
Encrypting keys
You can (re-)encrypt your signing keys using the encrypt_keys
script, which will prompt for the old passphrase (if any) and new passphrase:
script/encrypt_keys.sh keys/raven
The script/decrypt_keys.sh
script can be used to remove encryption, which is not recommended. The script exists primarily for internal usage to decrypt the keys in tmpfs to perform signing.
Enabling updatable APEX components
GrapheneOS uses the TARGET_FLATTEN_APEX := true
format to include APEX components as part of the base OS and disables support for out-of-band APEX component updates. This reduces complexity and attack surface along with simplifying key management since there aren't a bunch of additional components to sign. GrapheneOS has no use for out-of-band updates to APEX components since we update the OS for each device and don't need partial out-of-band updates for portable components.
APEX components that aren't flattened are a signed APK (used to verify updates) with an embedded filesystem image signed with an AVB key (for verified boot). Our release signing scripts has support for signing non-flattened APEX components with the releasekey and AVB key for the device. This secures it but wouldn't be usable for shipping out-of-band updates to APEX components across multiple devices. You could switch to using a single shared APEX APK signing key and AVB signing key. You'll also need to add parameters for additional device-specific APEX components not included in our release signing script which was set up based on the Pixel 6 and Pixel 6 Pro.
Consult the upstream documentation on generating these keys. It will likely be covered here in the future, especially if non-flattened APEX components become unavoidable.
Generating signed factory images and full update packages
Build and package up the tools needed to generate over-the-air update packages:
m otatools-package
Generate a signed release build with the release.sh script:
script/release.sh raven
The factory images and update package will be in out/release-raven-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 target_files
zip.
See the install page for information on how to use the factory images. See the usage guide section on sideloading updates for information on how to use the update packages.
Running script/release.sh
also generates channel metadata for the update server. If you configured the Updater client URL and set the build to include it (see the information on OFFICIAL_BUILD
above), you can push signed over-the-air updates via the update system. Simply upload the update package to the update server along with the channel metadata for the release channel, and it will be pushed out to the update client. The DEVICE-beta
and DEVICE-stable
metadata provide the Beta and Stable release channels used by the update client. The DEVICE-testing
metadata provides an internal testing channel for the OS developers, which can be temporarily enabled using adb shell setprop sys.update.channel testing
. The name is arbitrary and you can also use any other name for internal testing channels.
For GrapheneOS itself, the testing channel is used to push out updates to developer devices, followed by a sample future release to test that the release which is about to be pushed out to the Beta channel is able to update to a future release. Once it's tested internally, the release is pushed out to the Beta channel, and finally to the Stable channel after public testing. A similar approach is recommended for derivatives of GrapheneOS.
Generating delta updates
Incremental updates shipping only the changes between two versions can be generated as a much more efficient way of shipping updates than a full update package containing the entire operating system. The GrapheneOS Updater app will automatically use a delta update if one exists for going directly from the currently installed version to the latest release. In order to generate a delta update, the original signed target files package for both the source version and target version are needed. The script/generate_delta.sh
script provides a wrapper script for generating delta updates by passing the device, source version build number and target version build number. For example:
script/generate_delta.sh raven 2021102503 2021102613
The script assumes that the releases are organized in the following directory structure:
releases ├── 2022050700 │ └── release-raven-2022050700 └── 2022050800 └── release-raven-2022050800
Incremental updates are uploaded alongside the update packages and update metadata on the static web server used as an update server. The update client will automatically check for an incremental update and use it if available. No additional metadata is needed to make incremental updates work.