Build

Build targets

Smartphone targets:

• lynx (Pixel 7a)
• 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 bookworm, Ubuntu 23.04 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 (for verifying AOSP releases and also used internally by repo for self-update verification)
• openssh (for verifying GrapheneOS releases)
• 136GiB+ storage for a standard sync with history, 90GiB+ storage for a lightweight sync

Baseline build dependencies:

• x86_64 Linux build environment
• 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

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.

Additional Android Open Source Project build dependencies not provided by the source tree:

• diff (diffutils)
• freetype2, fontconfig 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.js 18 LTS
• 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.

mkdir grapheneos-13
cd grapheneos-13
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b 13
repo sync -j8

mkdir grapheneos-TAG_NAME
cd grapheneos-TAG_NAME
repo init -u https://github.com/GrapheneOS/platform_manifest.git -b refs/tags/TAG_NAME

curl https://grapheneos.org/allowed_signers > ~/.ssh/grapheneos_allowed_signers

cd .repo/manifests
git config gpg.ssh.allowedSignersFile ~/.ssh/grapheneos_allowed_signers
git verify-tag $(git describe)
cd ../..

repo sync -j8

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 -j8 again. You may need to add --force-sync if a repository 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.

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 variables replaced with the appropriate values:

DEVICE=raven
BUILD_ID=TQ2A.230405.003.E1
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, Pixel 7 Pro and Pixel 7a 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.

script/encrypt_keys.sh keys/raven

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.

script/generate_delta.sh raven 2021102503 2021102613

releases
├── 2022050700
│   └── release-raven-2022050700
└── 2022050800
    └── release-raven-2022050800

Kernel

The Linux kernel is built separately using an AOSP kernel build system wrapping the upstream Linux kernel build system. Since it's a separate build system from the rest of the OS, the kernels are built separately. Many of the repositories are shared with the rest of the OS including the repositories providing the prebuilt toolchain for reproducible builds not depending on the tools from the host OS.

Additional Linux kernel build dependencies for 4th and 5th generation Pixels not provided by the source tree:

• libgcc (for the host, not the target)
• binutils (for the host, not the target)

mkdir -p android/kernel/5.15
cd android/kernel/5.15
repo init -u https://github.com/GrapheneOS/kernel_manifest-5.15.git -b 13
repo sync -j8

BUILD_CONFIG=common/build.config.gki.x86_64 build/build.sh
cp -a out out-vendor-modules
BUILD_CONFIG=common-modules/virtual-device/build.config.virtual_device.x86_64 OUT_DIR=out-vendor-modules/android13-5.15 build/build.sh
find out-vendor-modules/android13-5.15/dist -type f -name '*.ko' -exec out/android13-5.15/common/scripts/sign-file sha256 out/android13-5.15/common/certs/signing_key.pem out/android13-5.15/common/certs/signing_key.x509 {} \;

ANDROID_BUILD_TOP=~/android/grapheneos-13
cp out/android13-5.15/dist/bzImage $ANDROID_BUILD_TOP/kernel/prebuilts/5.15/x86_64/kernel-5.15
cp out/android13-5.15/dist/System.map $ANDROID_BUILD_TOP/kernel/prebuilts/5.15/x86_64/System.map
cp out-vendor-modules/android13-5.15/dist/*.ko $ANDROID_BUILD_TOP/kernel/prebuilts/common-modules/virtual-device/5.15/x86-64/

mkdir -p android/kernel/5.10
cd android/kernel/5.10
repo init -u https://github.com/GrapheneOS/kernel_manifest-5.10.git -b 13
repo sync -j8

BUILD_CONFIG=common/build.config.gki.x86_64 build/build.sh
cp -a out out-vendor-modules
BUILD_CONFIG=common-modules/virtual-device/build.config.virtual_device.x86_64 OUT_DIR=out-vendor-modules/android13-5.15 build/build.sh
find out-vendor-modules/android13-5.10/dist -type f -name '*.ko' -exec out/android13-5.10/common/scripts/sign-file sha256 out/android13-5.10/common/certs/signing_key.pem out/android13-5.10/common/certs/signing_key.x509 {} \;

ANDROID_BUILD_TOP=~/android/grapheneos-13
cp out/android13-5.10/dist/bzImage $ANDROID_BUILD_TOP/kernel/prebuilts/5.10/x86_64/kernel-5.10
cp out/android13-5.10/dist/System.map $ANDROID_BUILD_TOP/kernel/prebuilts/5.10/x86_64/System.map
cp out-vendor-modules/android13-5.10/dist/*.ko $ANDROID_BUILD_TOP/kernel/prebuilts/common-modules/virtual-device/5.10/x86-64/

mkdir -p android/kernel/coral
cd android/kernel/coral
repo init -u https://github.com/GrapheneOS/kernel_manifest-coral.git -b 13
repo sync -j8

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

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

mkdir -p android/kernel/redbull
cd android/kernel/redbull
repo init -u https://github.com/GrapheneOS/kernel_manifest-redbull.git -b 13
repo sync -j8

BUILD_CONFIG=private/msm-google/build.config.redbull.vintf build/build.sh

mkdir -p android/kernel/raviole
cd android/kernel/raviole
repo init -u https://github.com/GrapheneOS/kernel_manifest-raviole.git -b 13
repo sync -j8

mkdir -p android/kernel/bluejay
cd android/kernel/bluejay
repo init -u https://github.com/GrapheneOS/kernel_manifest-bluejay.git -b 13
repo sync -j8

LTO=full BUILD_AOSP_KERNEL=1 ./build_slider.sh

LTO=full BUILD_AOSP_KERNEL=1 ./build_bluejay.sh

mkdir -p android/kernel/pantah
cd android/kernel/pantah
repo init -u https://github.com/GrapheneOS/kernel_manifest-pantah.git -b 13
repo sync -j8

LTO=full BUILD_AOSP_KERNEL=1 ./build_cloudripper.sh

mkdir -p android/kernel/lynx
cd android/kernel/lynx
repo init -u https://github.com/GrapheneOS/kernel_manifest-lynx.git -b 13
repo sync -j8

LTO=full BUILD_AOSP_KERNEL=1 ./build_lynx.sh

Browser and WebView

Vanadium is a hardened fork of Chromium developed by GrapheneOS and used to provide the WebView and optionally the standalone browser app. It tracks the Chromium release cycles along with having additional updates for downstream changes to the privacy and security hardening patches, so it's updated at a different schedule than the monthly Android releases.

The browser and the WebView are independent applications built from the Chromium source tree. The GrapheneOS browser build is located at external/vanadium and the WebView is at external/chromium-webview.

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

git clone https://github.com/GrapheneOS/Vanadium.git
cd Vanadium
git checkout CORRECT_BRANCH_OR_TAG

Generate a signing key for Vanadium if this is the initial build:

keytool -genkey -v -keystore vanadium.keystore -storetype pkcs12 -alias vanadium -keyalg RSA -keysize 4096 -sigalg SHA512withRSA -validity 10000 -dname "cn=GrapheneOS"

You will be prompted to enter a password which will be requested by the generate-release.sh script for signing releases. You should back up the generated keystore with your other keys.

Fetch the Chromium sources:

fetch --nohooks android

Sync to the latest stable release for Android (replace VERSION with the correct value):

cd src
git fetch --tags
git checkout VERSION

Apply the GrapheneOS patches on top of the tagged release:

git am --whitespace=nowarn --keep-non-patch ../patches/*.patch

Sync submodules and obtain build dependencies:

gclient sync -D --with_branch_heads --with_tags --jobs 32

Then, configure the build in the src directory:

gn args out/Default

Copy the GrapheneOS configuration from ../args.gn and save/exit the editor. Modify target_cpu as needed if the target is not arm64. For x86_64, the correct value for target_cpu is x64, but note that the Android source tree refers to it as x86_64.

You need to set trichrome_certdigest to the correct value for your generated signing key. You can obtain this with the following command:

keytool -export-cert -alias vanadium -keystore vanadium.keystore | sha256sum

Build the components:

chrt -b 0 ninja -C out/Default/ trichrome_webview_64_32_apk trichrome_chrome_64_32_apk trichrome_library_64_32_apk

Sign the apks:

../generate-release.sh out

The apks need to be copied from out/Default/apks/release/*.apk into the Android source tree at external/vanadium/prebuilt/arm64/ with arm64 substituted with the correct value for other architectures (arm, x86, x86_64).

WebView provider apps need to be whitelisted in frameworks/base/core/res/res/xml/config_webview_packages.xml. By default, only the Vanadium WebView is whitelisted.

Prebuilt apps

The official releases of our Auditor, Camera and PdfViewer apps are bundled as apks into external/ repositories. There are no modifications to these for GrapheneOS. These are built and signed with the standard gradle Android plugin build system.

The TalkBack screen reader is built from our talkback fork repository and included as a prebuilt signed with the OS releasekey. It may be presigned in the future similar to our standalone apps if we decide to do out-of-band releases.

Emulator

To test a build for the emulator, run emulator within the build environment. The emulator will use CPU hardware acceleration via KVM along with optional graphics acceleration via the host GPU if these are available. The emulator does not work on Wayland due to the AOSP provided Qt build missing the Wayland platform plugin.

Compatibility Test Suite

mkdir -p ~/android/cts/{arm,x86}
cd ~/android/cts/arm
curl -O https://dl.google.com/dl/android/cts/android-cts-12_r1-linux_x86-arm.zip
unzip android-cts-12_r1-linux_x86-arm.zip
rm android-cts-12_r1-linux_x86-arm.zip
curl -O https://dl.google.com/dl/android/cts/android-cts-verifier-12_r1-linux_x86-arm.zip
unzip android-cts-verifier-12_r1-linux_x86-arm.zip
rm android-cts-verifier-12_r1-linux_x86-arm.zip
cd ~/android/cts/x86
curl -O https://dl.google.com/dl/android/cts/android-cts-verifier-12_r1-linux_x86-x86.zip
unzip android-cts-verifier-12_r1-linux_x86-x86.zip
rm android-cts-verifier-12_r1-linux_x86-x86.zip
curl -O https://dl.google.com/dl/android/cts/android-cts-12_r1-linux_x86-x86.zip
unzip android-cts-12_r1-linux_x86-x86.zip
rm android-cts-12_r1-linux_x86-x86.zip
cd ~/android/cts
curl -O https://dl.google.com/dl/android/cts/android-cts-media-1.5.zip
unzip android-cts-media-1.5.zip
rm android-cts-media-1.5.zip

cd android-cts-media-1.5
./copy_images.sh
./copy_media.sh

./android-cts/tools/cts-tradefed

list modules

run cts --skip-device-info --module CTS_MODULE_NAME

run cts --skip-device-info --skip-preconditions --module CTS_MODULE_NAME

Programming languages

The following programming languages are acceptable for completely new GrapheneOS projects:

• Kotlin for apps and any services closely tied to the apps, now that it's not only officially supported by the Android SDK and Android Studio but also the default language with Kotlin exclusive enhancements to the APIs
• Web applications must be entirely static HTML/CSS/JavaScript. TypeScript would make sense at a larger scale but there are no plans for any large web applications.
• Rust with no_std for low-level code used in a hypervisor, kernel, daemon, system library, etc. Keep in mind that low-level code is to be avoided whenever a higher-level language is better suited to the job. In general, the project aims to avoid creating more low-level code manually dealing with memory ownership and lifetimes in the first place.
• C in rare cases for very small and particularly low-level projects without opportunities to reduce the trusted computing base for memory corruption to any significant degree with Rust, such as for the hardened_malloc project
• arm64 assembly in extremely rare cases where C or Rust aren't usable with compiler intrinsics
• Python 3 for small (less than 500 lines) development-related scripts that are not exposed to untrusted input. It's never acceptable to use it for client-side code on devices or for servers. It isn't used on the servers even for non-application-server code.
• Bash for tiny (less than 200 lines) build scripts without any non-trivial logic where Python would be an annoyance.

Much of the work is done on existing projects, and the existing languages should be used unless there are already clear stable API boundaries where a different language could be used without causing a substantial maintenance burden. The following languages are typical from most to least common: Java, C++, C, JavaScript, arm64 assembly, POSIX shell, Bash.

Code style

For existing projects, use the official upstream code style. Avoid using legacy conventions that they're moving away from themselves. Follow the code style they use for new additions. Some projects have different code styles for different directories or files depending on their sources, in which case respect the per-file style.

For new projects, follow the official code style for the language. Treat the standard library APIs as defining the naming style for usage of the language, i.e. C uses variable_or_function_name, type_name, MACRO_NAME while JavaScript uses variable_or_function_name, ClassName and CONSTANT_NAME. For Python, follow PEP8 and the same goes for other languages with official styles whether defined in a document or by the default mode for the official formatting tool like rustfmt.

For cases where there isn't an official or prevailing code style for other things, avoid tabs, use 4-space indents, function_name, variable_name, TypeName and CONSTANT_NAME. Prefer single-line comment syntax other than rare cases where it makes sense to add a tiny comment within a line of code. In languages with the optional braces misfeature (C, C++, Java), always use them. Open braces on the same line as function definitions / statements. Wrap lines at 100 columns except in rare cases where it would be far uglier to wrap the line.

For JavaScript, all code should be contained within ES6 modules. This means every script element should use type="module". Modules provide proper namespacing with explicit imports and exports. Modules automatically use strict mode, so "use strict"; is no longer needed. By default, modules are also deferred until after the DOM is ready, i.e. they have an implicit defer attribute. This should be relied upon rather than unnecessarily listening for an event to determine if the DOM is ready for use. It can make sense to use async to run the code earlier if the JavaScript is essential to the content and benefits from being able to start tasks before the DOM is ready, such as retrieving important content or checking if there's a login session. Always end lines with semicolons (since automatic insertion is poorly designed) and always use const to declare variables, unless they are reassigned in which case they should be declared with let but never use var as it is effectively broken. Try to prefer loops with for..of. JavaScript must pass verification with eslint using the following .eslintrc.json configuration:

{
    "env": {
        "browser": true,
        "es2022": true
    },
    "extends": "eslint:recommended",
    "parserOptions": {
        "ecmaVersion": 2022,
        "sourceType": "module"
    },
    "rules": {
        "indent": [
            "error",
            4
        ],
        "linebreak-style": [
            "error",
            "unix"
        ],
        "quotes": [
            "error",
            "double"
        ],
        "semi": [
            "error",
            "always"
        ],
        "no-var": [
            "error"
        ]
    }
}

Cookies are only used for login sessions. The only other use case considered valid would be optimizing HTTP/2 Server Push but the intention is only to use that for render blocking CSS and it's not really worth optimizing for caching when the CSS is tiny in practice. Every cookie must have the __Host prefix to guarantee that it has the Secure attribute and Path=/. The HttpOnly and SameSite=Strict flags should also always be included. These kinds of cookies can provide secure login sessions in browsers with fully working SameSite=Strict support. However, CSRF tokens should still be used for the near future in case there are browser issues.

For web content, use dashes as user-facing word separators rather than underscores. Page titles should follow the scheme "Page | Directory | Higher-level directory | Site" for usability with a traditional title as the Open Graph title.

HTML must pass verification with validatornu and xmllint. Ensuring that it parses as XML with xmllint catches many common mistakes and typos that are missed by HTML validation due to the ridiculously permissive nature of HTML. This enforces closing every tag, using proper escaping and so on. XHTML does not really exist anymore and we simply use XML parsing as an enforced coding standard and lint pass. It can also be useful to make it compatible with XML-based tooling.

Avoid designing around class inheritance unless it's a rare case where it's an extremely good fit or the language sucks (Java) and it's the least bad approach, but still try to avoid it.

Use concise but self-explanatory variable names. Prefer communicating information via naming rather than using comments whenever possible. Don't name variables i, j, k, etc. like C programmers. It's okay to use things like x and y for parameters if the function is genuinely that generic and operates on arbitrary values. In general, try to scope variables into the most limited scope (in C or C++, be careful about this when references are taken).

Write code that's clean and self-explanatory. Use comments to explain or justify non-obvious things, but try to avoid needing them in the first place. In most cases, they should just be communicating non-local information such as explaining why an invariant is true based on the code elsewhere (consider a runtime check to make sure it's true, or an assertion if performance would be an issue). Docstrings at the top of top-level functions, modules, etc. are a different story and shouldn't be avoided.

Library usage

Make extensive usage of well designed standard library modules. For apps, treat Jetpack (androidx) as part of the standard library and make good use of it. For Java, Guava can also be treated as part of the standard library.

Libraries outside of the standard library should be used very cautiously. They should be well maintained, stable, well tested and widely used. Libraries implemented with memory unsafe languages should generally be avoided (one exception: SQLite).

Generally, frameworks and libraries existing solely to provide different paradigms and coding patterns are to be avoided. They increase barrier to entry for developers, generally only increase complexity unless used at very large scales (and may not even make things simpler in those cases) and come and go as fads. This is only okay when it's part of the standard libraries or libraries that are considered standard (androidx, Guava) by GrapheneOS and should still be approached cautiously. Only use it if it truly makes the correct approach simpler. Ignore fads and figure out if it actually makes sense to use, otherwise just stick to the old fashioned way if the fancy alternatives aren't genuinely better.