Build
-This is temporarily a stub since the old building instructions need to be ported - over to this web format.
+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 +
- 200GiB 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
+ succeed.
+
+ 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/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.
Chromium 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_patches 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
+ Chromium's Android build instructions for details on obtaining the prerequisites.
+
+ mkdir chromium +cd chromium +fetch --nohooks android+ +
Sync to the latest stable release for Android (replace $VERSION with the correct + value):
+ +gclient sync --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 src directory:
gn args out/Default+ +
You can obtain the proper configuration from the + + GrapheneOS chromium_build repository.
+ +To build Monochrome, which provides both Chromium and the WebView:
+ +ninja -C out/Default/ monochrome_public_apk+ +
The apk needs to be copied from out/Default/apks/MonochromePublic.apk
+ into the Android source tree at
+ external/chromium/prebuilt/arm64/MonochromePublic.apk
Standalone builds of Chromium and the WebView can be done via the
+ chrome_modern_public_apk and 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
+ frameworks/base/core/res/res/xml/config_webview_packages.
Kernel
+ +The kernel needs to be built in advance, since it uses a separate build system.
+ +For example, to build the kernel for blueline:
+ +cd kernel/google/crosshatch +./build.sh blueline+ +
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 XL.
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 (aosp_crosshatch is the Pixel 3 XL):
+
+
choosecombo release aosp_marlin 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.
+
+
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.
+ +Extracting vendor files for Pixel devices
+ +This section does not apply to devices with no extra vendor files are required.
+ +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 + passed.
+ +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. Keys must be generated before building + for the Pixel and Pixel XL due to needing to provide the keys to the kernel build system, but this + step can be done after building for Nexus devices.
+ +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.
+ +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 ../..+ +
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.
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+ +
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:
+ +make -j20+ +
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 signed factory images and full update packages
+ +Generate a signed release build with the release.sh script:
+ +script/release.sh crosshatch+ +
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 target_files
+ zip.
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.
+