<- Back to documentation

Building CopperheadOS from source

Build dependencies

  • x86_64 Linux build environment (OS X is not supported, unlike AOSP)
  • Android Open Source Project build dependencies
  • Linux kernel build dependencies
  • gradle 2.14.1 (for F-Droid)
  • Android SDK and assorted support packages (for F-Droid)

Downloading source code

Note that 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.

Development branch

A single development branch is currently used to support the Nexus 9, 5X and 6P:

mkdir copperheados-nougat-mr0.5-release
cd copperheados-nougat-mr0.5-release
repo init -u -b nougat-mr0.5-release
repo sync -j16

Note that this branch will change to nougat-mr1-release and then nougat-mr2-release at some point, when AOSP makes that switch. Existing devices may also split off into their own branches and new devices will likely be supported by separate branches until the next major stable release of AOSP.

Stable release

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-NRD90U.2016.
cd copperheados-NRD90U.2016.
repo init -u -b refs/tags/NRD90U.2016.

Verify the manifest:

gpg --recv-keys 65EEFE022108E2B708CBFCF7F9E712E59AF5F22A
gpg --recv-keys 4340D13570EF945E83810964E8AD3F819AB10E78
cd .repo/manifests.git
git verify-tag --raw $(git describe)
cd ../..

Complete the source tree download:

repo sync -j16

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 run repo sync -j16 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.


You should have at least 16GiB of memory and lots of free disk space to build.

The build has to be done from bash as is not compatible with other shells like zsh.

Set up the build environment:

source build/
export LANG=C
export BUILD_NUMBER=$(date --utc +%Y.%m.%d.%H.%M.%S)

Select the desired build target (aosp_bullhead is the Nexus 5X):

choosecombo release aosp_bullhead 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.

Start the build process:

make dist -j4

Generated signed factory images and/or an upgrade zip

Next, keys need to be generated for signing the build. The sample certificate subject can be replaced with your own information or simply left as-is.

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.

mkdir keys
cd keys
../development/tools/make_key releasekey '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../development/tools/make_key platform '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../development/tools/make_key shared '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../development/tools/make_key media '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
../development/tools/make_key verity '/C=CA/ST=Ontario/L=Toronto/O=CopperheadOS/OU=CopperheadOS/CN=CopperheadOS/'
cd ..

Generate the verity public key:

make generate_verity_key
out/host/linux-x86/bin/generate_verity_key -convert keys/verity.x509.pem keys/verity_key

Generate a signed release build with the script:

./ bullhead

The factory images and update package will be in out/release-bullhead.


user_error() {
  echo user error, please replace user and try again >&2
  exit 1

[[ $# -eq 1 ]] || user_error
[[ -n $BUILD_NUMBER ]] || user_error


source device/common/

get_radio_image() {
  grep -Po "require version-$1=\K.+" vendor/$2/vendor-board-info.txt | tr '[:upper:]' '[:lower:]'

if [[ $1 == bullhead ]]; then
  BOOTLOADER=$(get_radio_image bootloader lge/$1)
  RADIO=$(get_radio_image baseband lge/$1)
elif [[ $1 == flounder ]]; then
  BOOTLOADER=$(get_radio_image bootloader htc/$1)
elif [[ $1 == angler ]]; then
  BOOTLOADER=$(get_radio_image bootloader huawei/$1)
  RADIO=$(get_radio_image baseband huawei/$1)

VERSION=$(grep -Po "export BUILD_ID=\K.+" build/core/ | tr '[:upper:]' '[:lower:]')

mkdir -p $OUT || exit 1


if [[ $DEVICE == bullhead ]]; then
  EXTRA_OTA=(-b device/lge/bullhead/update-binary)

build/tools/releasetools/sign_target_files_apks -o -d "$KEY_DIR" \
  --replace_verity_public_key "$KEY_DIR/" --replace_verity_private_key "$KEY_DIR/verity" \
  out/dist/aosp_$DEVICE-target_files-$ $OUT/$TARGET_FILES || exit 1

build/tools/releasetools/ota_from_target_files --block -k "$KEY_DIR/releasekey" "${EXTRA_OTA[@]}" $OUT/$TARGET_FILES \
  $OUT/$DEVICE-ota_update-$ || exit 1

build/tools/releasetools/img_from_target_files -n $OUT/$TARGET_FILES \
  $OUT/$DEVICE-img-$ || exit 1

cd $OUT || exit 1

source ../../device/common/

Prebuilt code

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. AOSP only includes the WebView as Chrome is added as part of the Google Play components. There are prebuilt apks bundled at platform/external/chromium and platform/external/chromium-webview.

Note that it’s currently only possible to build the standalone Chromium app. The Nougat support code for the WebView has not yet landed upstream from the internal Google source tree, so the WebView is temporarily a proprietary app with no alternative to the official Google builds.

See Chromium’s Android build instructions for details on obtaining the prerequisites.

mkdir chromium
cd chromium
fetch --nohooks android

Sync to the latest stable revision, which was 54.0.2840.68 at the time of writing:

gclient sync --with_branch_heads -r 54.0.2840.68

Then, configure the build:

cd src
gn args out/Default

CopperheadOS configuration:

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"

For the 32-bit builds, replace "arm64" with "arm".

To build Chromium:

ninja -C out/Default/ chrome_public_apk

To build the WebView:

ninja -C out/Default/ system_webview_apk

The 64-bit ARM WebView apk is a special case. The ninja build will produce a pure 64-bit apk, which then needs to be merged with the 32-bit apk:

android_webview/tools/ --apk_32bit webview32.apk --apk_64bit webview64.apk \
    --out_apk merged.apk --zipalign_path /opt/android-sdk/build-tools/23.0.2/zipalign \
    --keystore_path build/android/ant/chromium-debug.keystore --key_name chromiumdebugkey \
    --key_password chromium --shared_library

The apks are signed as part of the build process for the OS after they’re bundled into external/chromium and external/chromium-webview.


A prebuilt Silence app is included in platform/external/Silence as a replacement for the AOSP Messaging app. It has many external dependencies including legacy Android SDK dependencies so an in-tree build is impractical right now.

See the Silence build instructions for details.