CalyxOS is Android-based, and the usual procedure to build AOSP applies. If you’re already familiar and setup to build Android, you can see the short version to get a quick idea. Otherwise, the long version goes into full detail to set it up from scratch.
This will help you setup a build environment for CalyxOS from scratch
- Linux, specifcally Debian Stable is preferred and is used for official builds
- Other recent Linux distros (Arch, Ubuntu, Fedora amongst many others) should mostly work just fine
- Windows will work too, using WSL2 (Windows Subsystem for Linux)
- macOS isn’t supported
- Android building is a very intensive process, and requires a lot of resources
- Approximately 250GB of free disk space (preferably on a fast SSD), more if you want to build for multiple devices
- At least 16GB of RAM, although 32GB or 64GB will give you a much better experience, especially if trying to use the computer while building
- A reasonably fast / unmetered internet connection, as the initial source code download is quite large (approximately 50GB)
For Debian Stable and other Debian based distros:
sudo apt update && sudo apt install bc git curl zip m4 rsync python3-protobuf default-jdk-headless default-jre-headless libncurses5 libncurses5-dev libssl-dev
Other distributions may have the same or similar names for packages.
You may need to run the below command to prevent some warnings when building
sudo sysctl -w kernel.unprivileged_userns_clone 1
Downloading the source code
repo is the tool used to download all the different CalyxOS (and AOSP) source code repositories
mkdir ~/bin PATH=~/bin:$PATH curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo
Now you can download the CalyxOS source code.
mkdir ~/calyxos/android12L cd ~/calyxos/android12L repo init -u https://gitlab.com/CalyxOS/platform_manifest -b android12L repo sync -j8 # You may use a higher number here if you have a fast computer and fast internet
This will be a big download and may take a long time. Once it’s done, you can build CalyxOS
Phones need a lot of proprietary files to boot and for all hardware to work, we have automated scripts to download and set them up.
./calyx/scripts/pixel/device.sh sunfish # Replace sunfish (Pixel 4a) with your device codename here
You made it this far! Now you can finally build CalyxOS
source build/envsetup.sh lunch calyx_sunfish-user # Replace sunfish (Pixel 4a) with your device codename here, and user with userdebug if you want a debug build m # Yes, just the letter 'm'
This will be the longest step, it may take hours depending on your computer. Sit back and watch it build!
- You need to unlock your device. If you haven’t done so already, you can run
fastboot flashing unlockto unlock your device.
- After that, to install the freshly built images, run:
fastboot flashalldirectly from the source code folder.
Congrats! You just compiled and installed a build of CalyxOS on your device.
Components built outside the OS
To keep the OS build simple and fast we build some components separately outside the AOSP build system, and copy them to a
prebuilts repository so they don’t need to be built every time the OS is built. A list of those with links to build instructions:
Additionally, we include some apps from F-Droid in the build process. These are the upstream binaries shipped as-is without any modifications.
To build and run CalyxOS Emulator images, see Emulator