Building CopperheadOS from source
- x86_64 Linux build environment (OS X is not supported, unlike AOSP)
- Android Open Source Project build dependencies
- Linux kernel build dependencies
- 16GiB of memory or more
- 100GiB of free storage space
CopperheadOS currently supports the following devices:
- Nexus 9 (flounder) - deprecated, only receives bug fixes / security updates
- Nexus 5X (bullhead)
- Nexus 6P (angler)
- Pixel (sailfish)
- Pixel XL (marlin)
Downloading source code
Android’s source tree is huge, so this will use a lot of bandwidth and disk space.
You likely want to use the most recent stable tag, not the development branch.
The nougat-mr2-release branch is used for the Nexus 5X, 6P, Pixel and Pixel XL:
mkdir copperheados-nougat-mr2-release cd copperheados-nougat-mr2-release repo init -u https://github.com/CopperheadOS/platform_manifest.git -b nougat-mr2-release repo sync -j32
The legacy nougat-mr1.1-release branch is used for the Nexus 9:
mkdir copperheados-nougat-mr1.1-release cd copperheados-nougat-mr1.1-release repo init -u https://github.com/CopperheadOS/platform_manifest.git -b nougat-mr1.1-release repo sync -j32
Pick a specific build for a device from the downloads page and download the source tree. Note that some devices use different Android Open Source Project branches so they end up with different tags. Make sure to use the correct tag for a device.
mkdir copperheados-N4F26J.2017.01.26.14.27.36 cd copperheados-N4F26J.2017.01.26.14.27.36 repo init -u https://github.com/CopperheadOS/platform_manifest.git -b refs/tags/N4F26J.2017.01.26.14.27.36
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:
cd ../.. 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 switches branches/tags
To update the source tree, run the
repo init command again to select the branch or tag and then
repo sync -j32 again. 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 CopperheadOS
only provides a stable history via tags.
Setting up the 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_marlin is the Pixel XL):
choosecombo release aosp_marlin user
For a development build, you may want to replace
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.
Extracting vendor code from factory images (optional)
CopperheadOS currently makes pre-generated vendor repositories available. However, it’s important to understand how these repositories are generated and we may stop providing the pre-generated repositories in the near future.
Obtain android-prepare-vendor with the set of patches currently used for CopperheadOS:
git clone https://github.com/copperhead/android-prepare-vendor.git
Extract the vendor code corresponding to the matching release. The build id of the Google release doesn’t necessary match the CopperheadOS build id.
cd android-prepare-vendor ./execute-all.sh -d marlin -b NJH47D -o $(pwd)
Replace any previous vendor code:
cd .. rm -rf vendor/marlin cp -r android-prepare-vendor/marlin/njh47d/vendor .
Note that android-prepare-vendor is non-deterministic for apk and jar files where Google doesn’t provide them unoptimized / unstripped. This was unintentionally improved by Google for the Pixel and Pixel XL since Google stopped including odex files in the main system image and they are now provided as unstripped apk files.
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 marlin (you should use unique keys per device variant):
mkdir keys/marlin cd keys/marlin ../../development/tools/make_key releasekey '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/emailAddressemail@example.com' ../../development/tools/make_key platform '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/emailAddressfirstname.lastname@example.org' ../../development/tools/make_key shared '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/emailAddressemail@example.com' ../../development/tools/make_key media '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/emailAddressfirstname.lastname@example.org' ../../development/tools/make_key verity '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/emailAddressemail@example.com' 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/verity_user.der.x509
The same kernel and device repository is used for the Pixel and Pixel XL. There’s no separate sailfish kernel.
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 signed factory images and full update packages
For the Pixel and Pixel XL, 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
Like the Android Open Source Project, CopperheadOS contains some code that’s built separately and then bundled into the source tree as binaries. Ideally, everything would be built-in tree with the AOSP build system but it’s not always practical.
Unlike AOSP, CopperheadOS builds the kernel as part of the operating system rather than bundling a pre-built kernel image.
Chromium and WebView
Chromium and the WebView are independent applications built from the Chromium source tree. The CopperheadOS 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 --target_os_only=true
Sync to the latest stable release for Android:
gclient sync --with_branch_heads -r 59.0.3071.125 --jobs 32
Apply the CopperheadOS patches on top of the tagged release:
git clone https://github.com/CopperheadOS/chromium_patches.git cd src git am ../chromium_patches/*.patch
Note that we don’t have our own public repository at the moment because Chromium is too large to host it on GitHub or Bitbucket where we are hosting the other repositories.
Then, configure the build in the
gn args out/Default
target_os = "android" target_cpu = "arm64" is_debug = false is_official_build = true is_component_build = false symbol_level = 0 ffmpeg_branding = "Chrome" proprietary_codecs = true android_channel = "stable" android_default_version_name = "59.0.3071.125" android_default_version_code = "307112552"
To build Monochrome, which provides both Chromium and the WebView:
ninja -C out/Default/ monochrome_public_apk
The apk is bundled directly into external/chromium and is signed as part of the OS build process.
For development, you can also make standalone builds:
To build Chromium:
ninja -C out/Default/ chrome_modern_public_apk
To build the WebView:
ninja -C out/Default/ system_webview_apk
Note that you’ll need to change org.chromium.chrome to com.android.webview in
F-Droid is built from the CopperheadOS fdroidclient repository and then bundled as an apk in the external/F-Droid repository.
The privileged extension built from source from the packages/apps/F-Droid/privileged-extension repository as part of the normal build process.
Etar, Offline Calendar, Net Monitor and Silence are simply built from the latest upstream tag and bundled as apks into external/ repositories. There are no modifications to these apps.